PT-2714: Add Design Principles and UX Review Process Storybook articles

[merchako]

Summary

• Adds Guidelines/UI Review — a checklist-led article (written by Alex Mercado, UX) covering how to get a UI work item through UX review to Done:
  • Pre-review checklist for quick reference
  • Submission instructions with Discord channel links
  • Reference section: Jira UX review property states, acceptance criteria ownership table (code review, UX review, QA), subtask review model, Storybook deliverable requirement, and how to link to reference UI
• Adds Guidelines/Design Principles — opinionated, example-driven guidelines covering button labels and variants, icon usage, semantic color pairing, editor toolbar conventions, tooltip rules, keyboard shortcut formatting, and keyboard navigation/focus guidance. Each guideline is illustrated with live Do/Don't component previews.
• Adds ExampleBlock / ExampleBlockGroup — a new Storybook utility component for annotating Do/Don't/Tip patterns in any MDX doc page with optional live component previews, used throughout Design Principles
• Updates tailwind.config.ts to include .mdx files in the content scan so Tailwind classes used inline in MDX are emitted
• Adds usage docs for ExampleBlock to the Intro page

Notes for reviewers

Warning

Prettier does not currently format .mdx files in this repo. MDX formatting won't be enforced by the pre-commit hook, so expect inconsistent whitespace in the new doc files. Don't flag formatting in review — it's a tooling gap, not an oversight.

Jira

https://paratextstudio.atlassian.net/browse/PT-2714

🤖 Generated with Claude Code

---

This change is 

[irahopkinson]

Thanks for getting this started.

@irahopkinson reviewed 3 files and all commit messages, and made 7 comments.
Reviewable status: all files reviewed, 6 unresolved discussions (waiting on merchako).

---

lib/platform-bible-react/src/stories/guidelines/design-principles.mdx line 0 at r1 (raw file):
What about tooltips in general? Where should they be typically used? What about in toolbars?

---

lib/platform-bible-react/src/stories/guidelines/design-principles.mdx line 54 at r1 (raw file):

---

## Editor toolbars and action buttons

What about button verbage? Should it be OK and 'Cancelor should the OK text be a call to action? Is action text likeSaveenough or should it beSave comment`?

---

lib/platform-bible-react/src/stories/guidelines/ui-review.mdx line 18 at r1 (raw file):

### Pre-Review Checklist
- [ ] Acceptance criteria are checked off or explicitly declared in the Jira work item

We have been using Definition of done rather than Acceptance criteria. It would be better if this doc used the right term.

Code quote:

Acceptance criteria

---

lib/platform-bible-react/src/stories/guidelines/ui-review.mdx line 22 at r1 (raw file):

- [ ] Storybook stories or documentation demonstrate the work
- [ ] The PR description links to any reference UIs using specific file paths and [Storybook](https://paranext.github.io/paranext-core/platform-bible-react-storybook/) links
- [ ] (optional) A narrated before/after video or screen recording is posted in the PR description or Jira work item, or else a meeting is requested

BTW this hasn't been optional - lately we have asked devs to add video to all their PRs where appropriate.

---

lib/platform-bible-react/src/stories/guidelines/ui-review.mdx line 32 at r1 (raw file):

- A brief description of what was done

Also include a link to the Jira work item **in the PR description**, so it is traceable from the code change.

BTW we don't typically do this because we don't want the GH repo commits littered with Jira links. However typically a branch name starts with the Jira code and at least one commit starts with the Jira code (which serves as a "link"). Is this sufficient? If we put the Jira link in the UX Discord thread why does it need to be in the PR description also?

---

lib/platform-bible-react/src/stories/guidelines/ui-review.mdx line 49 at r1 (raw file):

| `review not needed` | UX approval explicitly not required |

### Acceptance criteria

We have been using Definition of done rather than Acceptance criteria. It would be better if this doc used the right term.

[merchako]

@merchako made 6 comments.
Reviewable status: 2 of 3 files reviewed, 6 unresolved discussions (waiting on irahopkinson).

---

lib/platform-bible-react/src/stories/guidelines/design-principles.mdx line 54 at r1 (raw file):

Previously, irahopkinson (Ira Hopkinson) wrote…

What about button verbage? Should it be OK and 'Cancelor should the OK text be a call to action? Is action text likeSaveenough or should it beSave comment`?

Button verbiage should be specific and visually scannable. It needs to give the user an idea of what's going to happen if they click on it—Even if they haven't read all of the fine print above the buttons.

The cancel-OK paradigm is very bad at this. Users become trained to hit OK just to make messages go away. Therefore, we want to avoid the OK button and instead use a more specific called action. Cancel is sometimes fine, but usually there's a more descriptive. For example, Consider that a user has composed a message and tried to navigate away, but the system has interrupted them because it needs to know whether it should submit what they wrote or get rid of it. It doesn't have the capability to save drafts.

Bad labels: Cancel - OK
Decent labels: Cancel - Comment (what Google Docs uses)
Recommended labels: Discard - Comment

---

lib/platform-bible-react/src/stories/guidelines/design-principles.mdx line at r1 (raw file):

Previously, irahopkinson (Ira Hopkinson) wrote…

What about tooltips in general? Where should they be typically used? What about in toolbars?

Yes, tooltips should generally be used. Tooltips are absolutely required for every icon button and any UI control that doesn't have words, including in toolbars.

Tooltips need to be short enough to be easily scannable.

Tooltips are supplementary and should not be redundant. Do not use tooltips if the only thing contained in the tooltip is to repeat the label.

---

I'll add some content.

---

lib/platform-bible-react/src/stories/guidelines/ui-review.mdx line 18 at r1 (raw file):

Previously, irahopkinson (Ira Hopkinson) wrote…

We have been using Definition of done rather than Acceptance criteria. It would be better if this doc used the right term.

see below

---

lib/platform-bible-react/src/stories/guidelines/ui-review.mdx line 22 at r1 (raw file):

Previously, irahopkinson (Ira Hopkinson) wrote…

BTW this hasn't been optional - lately we have asked devs to add video to all their PRs where appropriate.

Nice! Thanks.

---

lib/platform-bible-react/src/stories/guidelines/ui-review.mdx line 32 at r1 (raw file):

Previously, irahopkinson (Ira Hopkinson) wrote…

BTW we don't typically do this because we don't want the GH repo commits littered with Jira links. However typically a branch name starts with the Jira code and at least one commit starts with the Jira code (which serves as a "link"). Is this sufficient? If we put the Jira link in the UX Discord thread why does it need to be in the PR description also?

Could you help me understand the cost of having the repo littered with
Jira links?

It's just so darn convenient to be able to click on a link to go to exactly the right repo. I find that there's a ton of jumping between fragmented data stores in the process of reviewing: Discord, GitHub, Jira, Reviewable, and the codebase—so any way I can make that jumping easier is a helpful.

---

lib/platform-bible-react/src/stories/guidelines/ui-review.mdx line 49 at r1 (raw file):

Previously, irahopkinson (Ira Hopkinson) wrote…

We have been using Definition of done rather than Acceptance criteria. It would be better if this doc used the right term.

My intention was to make "Definition of Done" one of these articles as a consistent reference of quality so we don't have to repeat ourselves so much in our Jira tickets. Then, Acceptance Criteria could be the Definition of Done plus whatever special about that work item.

But if you'd prefer to make them match for now and make that change as a separate effort, that's fine with me.

---

Now that we're using agents for reviews, I'm finding it increasingly important to match industry definitions of terminology like this.

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 3 additional findings.