feat(awards): Explain award categories (#156)

* feat(awards): Explain award categories

Co-Authored-By: Billy Vong <billy@sentry.io>

* fix(awards): Use official category descriptions

Co-Authored-By: Billy Vong <billy@sentry.io>

* fix(awards): Keep category descriptions in checkbox names

Remove the checkbox aria-label override so screen readers announce the
visible award description from the wrapping label.

* fix(awards): Stabilize category description matching

Use locale-independent lowercasing and keep unknown-category fallback
copy neutral across voting, ballot, and award-roll surfaces.

---------

Co-authored-by: sentry-junior[bot] <264270552+sentry-junior[bot]@users.noreply.github.com>
Co-authored-by: Billy Vong <billy@sentry.io>

Author: sentry-junior[bot]

src/app/awardCategories.ts

@@ -0,0 +1,34 @@
+const CATEGORY_GUIDANCE = [
+  {
+    matches: ['best use of ai'],
+    description: 'Clever and innovative twists with AI.',
+  },
+  {
+    matches: ['for the devs'],
+    description: 'Tools, workflows, or features that make developer life better.',
+  },
+  {
+    matches: ['just ship it already'],
+    description: 'The project so useful or obvious you wonder why it isn’t live yet.',
+  },
+  {
+    matches: ['sentry af'],
+    description: 'The one that feels the most “us”: quirky, sharp, unmistakably Sentry.',
+  },
+  {
+    matches: ['the quiet win'],
+    description: 'Small but mighty improvements that make a big difference.',
+  },
+] as const;
+
+const DEFAULT_GUIDANCE =
+  'A focused award category for projects that best fit this theme.';
+
+export function getAwardCategoryDescription(name: string) {
+  const normalizedName = name.trim().toLowerCase();
+  return (
+    CATEGORY_GUIDANCE.find(({matches}) =>
+      matches.some((match) => normalizedName.includes(match)),
+    )?.description ?? DEFAULT_GUIDANCE
+  );
+}

src/app/components/ProjectForm.tsx

@@ -1,6 +1,7 @@
 import {useEffect, useId, useState, type FormEvent, type KeyboardEvent} from 'react';
 
 import type {ProjectDetail, ProjectWriteRequest} from '../../shared/projects';
+import {getAwardCategoryDescription} from '../awardCategories';
 import {useProjectOptions} from '../queries/projects';
 
 export function ProjectForm({
@@ -437,7 +438,10 @@ export function ProjectForm({
                             disabled={nominationsLocked || (atLimit && !selected)}
                             onChange={() => toggleNomination(category.id)}
                           />
-                          <span>{category.name}</span>
+                          <span className="awardCategoryChoiceCopy">
+                            <strong>{category.name}</strong>
+                            <small>{getAwardCategoryDescription(category.name)}</small>
+                          </span>
                           {atLimit && !selected && <small>two selected</small>}
                         </label>
                       );

src/app/components/ProjectVoting.tsx

@@ -5,6 +5,7 @@ import type {
   BallotSelection,
   BallotStatusResponse,
 } from '../../shared/administration';
+import {getAwardCategoryDescription} from '../awardCategories';
 import {useVoteMutation} from '../queries/administration';
 
 export function ProjectVoting({
@@ -113,6 +114,9 @@ export function ProjectVoting({
                 </span>
                 <div className="projectVotingCategoryCopy">
                   <h3>{category.name}</h3>
+                  <p className="awardCategoryDescription">
+                    {getAwardCategoryDescription(category.name)}
+                  </p>
                   {!entered ? (
                     selectedHere ? (
                       <p>

src/app/routes/ProjectsPage.tsx

@@ -2,6 +2,7 @@ import {useEffect, useRef, useState} from 'react';
 import {Link, useParams} from 'wouter';
 
 import type {BallotStatusResponse} from '../../shared/administration';
+import {getAwardCategoryDescription} from '../awardCategories';
 import {GroupManager} from '../components/GroupManager';
 import {ProjectCard} from '../components/ProjectCard';
 import {PageState, QueryState} from '../components/AppLayout';
@@ -254,6 +255,7 @@ export function ProjectsPage({isAdmin = false}: {isAdmin?: boolean}) {
                     href={`/years/${yearId}/projects/${award.projectId}`}
                   >
                     <span>{award.categoryName}</span>
+                    <small>{getAwardCategoryDescription(award.categoryName)}</small>
                     <strong>{award.projectName}</strong>
                   </Link>
                 ))}
@@ -446,7 +448,10 @@ function BallotOverview({
           <ul>
             {selections.map(({category, vote}) => (
               <li key={category.id}>
-                <span>{category.name}</span>
+                <span className="ballotCategoryCopy">
+                  <strong>{category.name}</strong>
+                  <small>{getAwardCategoryDescription(category.name)}</small>
+                </span>
                 {vote.projectActive && vote.nominationEligible ? (
                   <Link href={`/years/${yearId}/projects/${vote.projectId}`}>
                     {vote.projectName} <span aria-hidden="true">→</span>

src/app/styles.css

@@ -690,6 +690,17 @@ main {
   color: rgba(255, 255, 255, 0.62);
   font-size: 0.75rem;
 }
+.ballotCategoryCopy {
+  display: grid;
+  gap: 0.18rem;
+}
+.ballotCategoryCopy strong {
+  color: #fff;
+  font-size: 0.78rem;
+}
+.ballotCategoryCopy small {
+  line-height: 1.35;
+}
 .ballotSelections a {
   min-width: 0;
   overflow: hidden;
@@ -1127,6 +1138,11 @@ main {
   font-size: 0.72rem;
   font-weight: 600;
 }
+.awardStrip small {
+  color: var(--muted);
+  font-size: 0.68rem;
+  line-height: 1.4;
+}
 
 .groupManager {
   padding: 1.5rem;
@@ -1400,6 +1416,10 @@ main {
   font-size: 0.78rem;
   line-height: 1.45;
 }
+.projectVotingCategoryCopy .awardCategoryDescription {
+  max-width: 46rem;
+  margin-bottom: 0.55rem;
+}
 .projectVotingCategoryCopy p strong {
   color: var(--ink);
 }
@@ -2067,6 +2087,16 @@ main {
   color: var(--ink);
   font-size: 0.78rem;
 }
+.projectForm .awardCategoryChoiceCopy {
+  display: grid;
+  gap: 0.2rem;
+}
+.projectForm .awardCategoryChoiceCopy strong {
+  font-size: 0.82rem;
+}
+.projectForm .awardCategoryChoiceCopy small {
+  line-height: 1.4;
+}
 .awardCategoryChoice--limited > span {
   color: var(--muted);
 }

test/app/ProjectForm.test.tsx

@@ -159,8 +159,8 @@ describe('ProjectForm award targeting', () => {
     await userEvent.click(
       await screen.findByRole('radio', {name: /Focus on specific awards/}),
     );
-    const craft = screen.getByRole('checkbox', {name: 'Craft prize'});
-    const impact = screen.getByRole('checkbox', {name: 'Biggest impact'});
+    const craft = screen.getByRole('checkbox', {name: /Craft prize/});
+    const impact = screen.getByRole('checkbox', {name: /Biggest impact/});
     const moonshot = screen.getByRole('checkbox', {name: /Moonshot/});
     await userEvent.click(craft);
     await userEvent.click(impact);
@@ -201,11 +201,11 @@ describe('ProjectForm award targeting', () => {
     expect(
       await screen.findByRole('radio', {name: /Focus on specific awards/}),
     ).toHaveProperty('checked', true);
-    expect(screen.getByRole('checkbox', {name: 'Biggest impact'})).toHaveProperty(
+    expect(screen.getByRole('checkbox', {name: /Biggest impact/})).toHaveProperty(
       'checked',
       true,
     );
-    expect(screen.getByRole('checkbox', {name: 'Craft prize'})).toHaveProperty(
+    expect(screen.getByRole('checkbox', {name: /Craft prize/})).toHaveProperty(
       'checked',
       true,
     );
@@ -244,7 +244,7 @@ describe('ProjectForm award targeting', () => {
     await userEvent.click(
       await screen.findByRole('radio', {name: /Focus on specific awards/}),
     );
-    await userEvent.click(screen.getByRole('checkbox', {name: 'Moonshot'}));
+    await userEvent.click(screen.getByRole('checkbox', {name: /Moonshot/}));
     await userEvent.click(screen.getByRole('button', {name: 'Never mind'}));
 
     expect(confirmMock).toHaveBeenCalledTimes(1);
@@ -265,7 +265,7 @@ describe('ProjectForm award targeting', () => {
       'disabled',
       true,
     );
-    expect(screen.getByRole('checkbox', {name: 'Moonshot'})).toHaveProperty(
+    expect(screen.getByRole('checkbox', {name: /Moonshot/})).toHaveProperty(
       'disabled',
       true,
     );
@@ -298,7 +298,7 @@ describe('ProjectForm award targeting', () => {
 
     focusedMode.focus();
     await userEvent.keyboard(' ');
-    const moonshot = screen.getByRole('checkbox', {name: 'Moonshot'});
+    const moonshot = screen.getByRole('checkbox', {name: /Moonshot/});
     moonshot.focus();
     await userEvent.keyboard(' ');
 

test/app/awardCategories.test.tsx

@@ -0,0 +1,27 @@
+import {describe, expect, it} from 'vitest';
+
+import {getAwardCategoryDescription} from '../../src/app/awardCategories';
+
+describe('getAwardCategoryDescription', () => {
+  it.each([
+    ['Best use of AI', 'Clever and innovative twists with AI.'],
+    ['For the devs!', 'Tools, workflows, or features that make developer life better.'],
+    [
+      'Just ship it already',
+      'The project so useful or obvious you wonder why it isn’t live yet.',
+    ],
+    [
+      'Sentry AF',
+      'The one that feels the most “us”: quirky, sharp, unmistakably Sentry.',
+    ],
+    ['The quiet win', 'Small but mighty improvements that make a big difference.'],
+  ])('describes %s with category-specific guidance', (name, expected) => {
+    expect(getAwardCategoryDescription(name)).toBe(expected);
+  });
+
+  it('gives new categories useful fallback guidance', () => {
+    expect(getAwardCategoryDescription('Wildcard')).toBe(
+      'A focused award category for projects that best fit this theme.',
+    );
+  });
+});