feat(stories): add content & voice principles (#100845)

Bringing the **Content & Voice** doc in from Notion.

Probably needs some small design updates, but the content is ready for
review.

---------

Co-authored-by: Jonas <[email protected]>
Co-authored-by: getsantry[bot] <66042841+getsantry[bot]@users.noreply.github.com>

Author: 3 people

knip.config.ts

@@ -17,6 +17,8 @@ const productionEntryPoints = [
   // this is imported with require.context
   'static/app/data/forms/*.tsx',
   // --- we should be able to get rid of those: ---
+  // Only used in stories (so far)
+  'static/app/components/core/quote/*.tsx',
   // Prevent exception until we build out coverage
   'static/app/components/prevent/virtualRenderers/**/*.{js,ts,tsx}',
   // todo we currently keep all icons

static/app/components/core/layout/container.tsx

@@ -105,6 +105,7 @@ interface ContainerLayoutProps {
 export type ContainerElement =
   | 'article'
   | 'aside'
+  | 'blockquote'
   | 'div'
   | 'figure'
   | 'footer'

static/app/components/core/layout/stack.tsx

@@ -12,7 +12,8 @@ type StackLayoutProps = Pick<
   'align' | 'direction' | 'gap' | 'justify' | 'wrap'
 >;
 
-type StackProps<T extends ContainerElement = 'div'> = StackLayoutProps & FlexProps<T>;
+export type StackProps<T extends ContainerElement = 'div'> = StackLayoutProps &
+  FlexProps<T>;
 
 const StackComponent = styled(
   <T extends ContainerElement = 'div'>({

static/app/components/core/principles/content-and-voice/content-and-voice.mdx

@@ -0,0 +1,104 @@
+---
+title: Content & Voice
+layout: document
+description: Sentry's unique brand voice sets us apart—learn how to approach content and voice in Sentry's UI.
+---
+
+## Tone
+
+There are two different ways to write copy within the Sentry app. There’s normal **plain speech**, and there’s our branded, personality-rich “**Sentry Voice**.” Sentry Voice is a little snarky (but never mean), jokey, and quick-witted. The jokes should be simple, if it needs explanation, it isn’t gonna work.
+
+Generally, you should default to plain and clear speech in the product. This includes page names, table headings, widgets, CTAs, Seer responses, and descriptive text. Occasionally it will be appropriate to use the “Sentry Voice,” like on 404 pages, new product announcements and other areas that don’t directly interfere with someone’s workflow. Within the product, assume users are frustrated and in a hurry — above all our goal is to make sure they can find what they are looking for quickly, and explain what is happening clearly.
+
+### Examples
+
+**Plain speech**
+
+> Issues are groups of errors that have a similar stacktrace. Set an alert for new issues, when an issue changes state, frequency of errors, or users affected by an issue.
+
+**Sentry Voice**
+
+> 404, Page not found. We looked. And then we gave up. [Button: *Return to a Real Page*]
+
+> Sentry Rollback is here. Forgot everything you did this year? Don’t worry—we have the receipts. Take a look back at your 2024 with Sentry.
+
+## When to Use “Sentry Voice” vs. Plain Speech
+
+**Do** use Sentry Voice for…
+
+- Designing a new product tour
+- Descriptions in the “What’s New” feature
+- Adding personality to a long (30+ second) loading state
+- High level loading states (404, 500, This Page Does Not Exist)
+- Onboarding, but use it sparingly. Make sure it is not getting in the way of helping users actually configure their account.
+- Empty states, also case-dependent. These should always have an actionable first line, but can have a snarky heading or second sentence.
+
+**Don’t** use Sentry Voice (and use plain speech instead) for…
+
+- Product UI. This includes page titles, labels, filters, search, table headings, CTAs, toasts, alerts, and callouts.
+- Non-marketing emails. Emails generated by weekly summaries or alerts should be straightforward and direct.
+- Settings pages. These are already complicated enough.
+- Documentation. Users are here to find information quickly and they need to be easily searchable.
+
+## Writing in “Sentry Voice”
+
+You should not be using this voice within regular workflows, or when someone is trying to complete a task. Even when using Sentry Voice make sure to front-load main information, and not let personality get in the way of content. For example in an error message, make sure the first few words of the body capture the problem first (_404 Page not found_. We looked. And then we gave up.).
+
+Here are three things to keep in mind when writing with personality on behalf of Sentry:
+
+1. **We have empathy for our users**: they should feel understood and like we appropriately grasp the gravity of their situation. Whatever they're going through, we get it. When we are snarky we are snarky towards the situation they are in, not towards the user themself.
+2. **We're self-aware**: look, we know were not curing cancer over here. We help developers, but we're not changing the world. Don't make bold claims with aspirational copy.
+3. **We have fun**: this stuff is dry, so look for opportunity to have fun with the copy (while keeping everything above in mind).
+4. **If you feel confused or unsure where and how to use Sentry Voice, ask our in-house copy writer in the `#discuss-design` Slack channel.**
+
+> [!TIP] Heads up!
+> If you're looking for more information, this was modified from the [brand identity writing style guide](https://brand.getsentry.com/document/5#/style-guides/writing-style-guide).
+
+## General Copywriting Guidelines
+
+**Keep it simple**—avoid jargon and don’t get fancy. If you are referencing new words or concepts explain them or link out to documentation.
+
+**Be informative**. Always provide straightforward, accurate information, we don't manipulate people into believing we’re anything more than we actually are.
+
+**Use American spelling**. Apologies to our colleagues who prefer the Queen’s English.
+
+**Avoid emotional punctuation**; for example use `!` sparingly.
+
+**Don’t use weird punctuation** like the interrobang `‽`. Not everyone shares your affinity for esoteric glyphs.
+
+**Be consistent.** Reference our [Icons + CTA Copy Table](https://sentry.sentry.io/stories/core/button#icons) to make sure you are using agreed upon terms in CTA Buttons.
+For example, Dashboards, Views, Monitors, and Automations are always “Edited” and use the pencil icon.
+When a user is creating a new Dashboard, View, or Monitor, the language should always be “Create [Object]” with a plus icon.
+
+**Use punctuation thoughtfully**. If you don’t know how to use colons `:` or semicolons `;` it is better not to try. Alternatively, ask a copywriter for help.
+
+> [!TIP] A brief aside on dashes
+> Hyphens, the `-` or `‐` symbol, are used to join words together or write compound numbers (_sixty-five_, _self-serve_).
+>
+> En-dashes, the `–` or `–` symbol, are most commonly used for time ranges (_2020–2022_, _September 1–September 3)_.
+> Insert these without a space on either side.
+>
+> Em-dashes, the `—` or `—` symbol, are the longest of the three and act more like true punctuation.
+> You can use these in place of a comma or parentheses, or to indicate when a sentence is taking a new turn.
+> (_We want to introduce users to Seer—a new name for our old AI product—which we have rebranded this month_.)
+>
+> For additional information, refer to [Merriam Webster](https://www.merriam-webster.com/grammar/em-dash-en-dash-how-to-use).
+
+## Use Title Case for Titles and Headings
+
+Within the app we use title case for all headings, CTAs and labels (including: chart titles, table, chart axes, chart legends, table titles, table column headers, form fields labels, anything in the sidebar).
+This means the first letter of every word is capitalized, except for conjunctions and “minor” words.
+
+This is true for `<Heading>`, as well as all CTAs, table headers, and default widgets. As a rule, we **never** use all caps in the product. If you see `text-transform: uppercase` anywhere, you should remove it.
+
+**Examples**
+
+> Last Seen (column header)
+
+> Save As… (CTA Button)
+
+> Errors and Outages (sidebar item & H1)
+
+> Most Frozen Frames (default widget title)
+
+Not sure how to convert something? Refer to [capitalizemytitle.com](https://capitalizemytitle.com/) for a quick gut check.

static/app/components/core/quote/index.tsx

@@ -0,0 +1 @@
+export {Quote} from './quote';

static/app/components/core/quote/quote.mdx

@@ -0,0 +1,91 @@
+---
+title: Quote
+description: A blockquote component for displaying extended quotations with optional source attribution and citations.
+source: 'sentry/components/core/quote'
+resources:
+  js: https://github.com/getsentry/sentry/blob/master/static/app/components/core/quote/quote.tsx
+---
+
+import * as Storybook from 'sentry/stories';
+
+import {Quote} from './quote';
+
+import documentation from '!!type-loader!@sentry/scraps/quote';
+
+export {documentation};
+
+The `Quote` component renders a `<blockquote>` element to indicate that the enclosed text is an extended quotation. It provides semantic HTML with proper styling and optional citation support through the `source` prop.
+
+## Basic Usage
+
+A simple quotation without attribution:
+
+<Storybook.Demo>
+  <Quote>It’s not a bug; it’s an undocumented feature.</Quote>
+</Storybook.Demo>
+```jsx
+<Quote>It’s not a bug; it’s an undocumented feature.</Quote>
+```
+
+## Props
+
+### Source Attribution
+
+The `source` prop accepts an object with optional `author`, `href`, and `label` properties for attribution and citation. These properties are rendered with proper semantic HTML using the `cite` attribute and `<cite>` element.
+
+#### With Author
+
+Provide attribution to a specific person or entity:
+
+<Storybook.Demo>
+  <Quote source={{author: 'Developer'}}>It’s not a bug, it’s a feature.</Quote>
+</Storybook.Demo>
+```jsx
+<Quote source={{author: 'Developer'}}>It’s not a bug, it’s a feature.</Quote>
+```
+
+#### With Author and Label
+
+Include both the author and additional context about the source:
+
+<Storybook.Demo>
+  <Quote source={{author: 'Developer', label: 'in complete denial'}}>
+    It’s not a bug, it’s a feature.
+  </Quote>
+</Storybook.Demo>
+```jsx
+<Quote source={{author: 'Developer', label: 'in complete denial'}}>
+  It’s not a bug, it’s a feature.
+</Quote>
+```
+
+#### With URL Reference
+
+The `href` property sets the `cite` attribute on the `<blockquote>` element, providing a machine-readable source reference:
+
+<Storybook.Demo>
+  <Quote
+    source={{
+      author: 'Developer',
+      label: 'in complete denial',
+      href: 'https://example.com/source',
+    }}
+  >
+    It’s not a bug, it’s a feature.
+  </Quote>
+</Storybook.Demo>
+```jsx
+<Quote
+  source={{
+    author: 'Developer',
+    label: 'in complete denial',
+    href: 'https://example.com/source',
+  }}
+>
+  It’s not a bug, it’s a feature.
+</Quote>
+```
+
+## Accessibility
+
+`<Quote>` uses semantic HTML to ensure quotes are correctly announced by assistive technologies, including the `cite` element for machine-readable source references.

static/app/components/core/quote/quote.tsx

@@ -0,0 +1,76 @@
+import {Fragment, type ReactNode} from 'react';
+import styled from '@emotion/styled';
+
+import {Stack} from '@sentry/scraps/layout';
+import type {StackProps} from '@sentry/scraps/layout/stack';
+import {Text} from '@sentry/scraps/text';
+
+// interface + type union because `extends` doesn't play nicely with generics
+interface QuoteBaseProps {
+  children: ReactNode;
+  source?: {
+    author?: string;
+    href?: string;
+    label?: string;
+  };
+}
+export type QuoteProps = QuoteBaseProps & Omit<StackProps<'blockquote'>, 'children'>;
+
+export function Quote(props: QuoteProps) {
+  const {children, ...spreadProps} = props;
+  return (
+    <Stack gap="md" as="figure" position="relative" {...spreadProps}>
+      <Line aria-orientation="vertical" />
+      <Blockquote cite={props.source?.href} as="blockquote">
+        {children}
+      </Blockquote>
+      {props.source ? (
+        <Caption>
+          <Text as="p">
+            &ndash;&nbsp;
+            {props.source.author}
+            {props.source?.label ? (
+              <Fragment>
+                , <cite>{props.source.label}</cite>
+              </Fragment>
+            ) : null}
+          </Text>
+        </Caption>
+      ) : null}
+    </Stack>
+  );
+}
+
+const Line = styled('hr')`
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  left: 0;
+  margin: 0;
+  border: none;
+  height: 100%;
+  width: 1px;
+  padding-left: ${p => p.theme.space.xl};
+  margin-left: ${p => p.theme.space.lg};
+  border-left: 1px solid ${p => p.theme.tokens.border.primary};
+`;
+
+const Blockquote = styled('blockquote')`
+  /**
+   * Reset any properties that might be set by the global CSS styles.
+   */
+  margin: 0;
+  padding: 0;
+  border: none;
+  padding-left: calc(${p => `${p.theme.space.xl} + ${p.theme.space.lg}`});
+`;
+
+const Caption = styled('figcaption')`
+  /**
+   * Reset any properties that might be set by the global CSS styles.
+   */
+  margin: 0;
+  padding: 0;
+  border: none;
+  padding-left: calc(${p => `${p.theme.space.xl} + ${p.theme.space.lg}`});
+`;

static/app/stories/view/storyMdxComponent.tsx

@@ -3,6 +3,7 @@ import React from 'react';
 import {type Callout as CalloutProps} from '@r4ai/remark-callout';
 
 import {Alert, type AlertProps} from '@sentry/scraps/alert';
+import {Quote, type QuoteProps} from '@sentry/scraps/quote/quote';
 
 import {InlineCode} from 'sentry/components/core/code';
 import {Stack} from 'sentry/components/core/layout';
@@ -61,4 +62,5 @@ export const storyMdxComponents = {
   ul: (props: Omit<HTMLProps<HTMLUListElement>, 'wrap'>) => (
     <Stack {...props} as="ul" gap="lg" />
   ),
+  blockquote: (props: QuoteProps) => <Quote {...props} />,
 };