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

.remarkrc.mjs

@@ -0,0 +1,20 @@
+// Remark configuration for MDX files in src/stories/.
+// Runs via `format:core: remark "./src/**/*.mdx" -o`
+// Mirrored by lib/platform-bible-react/.remarkrc.mjs
+
+const config = {
+  plugins: [
+    // Parse and serialize MDX syntax (JSX, imports, exports in markdown)
+    'remark-mdx',
+    // GitHub Flavored Markdown: tables, strikethrough, task lists
+    'remark-gfm',
+  ],
+  settings: {
+    // Use - for unordered list bullets (consistent with lib config)
+    bullet: '-',
+    // Use --- for thematic breaks (consistent with lib config)
+    rule: '-',
+  },
+};
+
+export default config;

.vscode/extensions.json

@@ -10,6 +10,7 @@
     "ms-dotnettools.csdevkit",
     "streetsidesoftware.code-spell-checker",
     "stylelint.vscode-stylelint",
+    "unifiedjs.vscode-mdx",
     "vitest.explorer"
   ]
 }

cspell.json

@@ -42,6 +42,7 @@
     "deleter",
     "deuterocanon",
     "dockbox",
+    "dont",
     "electronmon",
     "endregion",
     "eten",
@@ -60,6 +61,7 @@
     "lamport",
     "localizable",
     "localstorage",
+    "lucide",
     "maximizable",
     "networkable",
     "newtonsoft",
@@ -80,6 +82,7 @@
     "pubnumber",
     "reinitializing",
     "reserialized",
+    "saroj",
     "shadcn",
     "sillsdev",
     "sldr",

lib/platform-bible-react/.remarkrc.mjs

@@ -0,0 +1,19 @@
+// Remark configuration for MDX files in lib/platform-bible-react.
+// Mirrors root .remarkrc.json which covers src/stories/*.mdx.
+
+const config = {
+  plugins: [
+    // Parse and serialize MDX syntax (JSX, imports, exports in markdown)
+    'remark-mdx',
+    // GitHub Flavored Markdown: tables, strikethrough, task lists
+    'remark-gfm',
+  ],
+  settings: {
+    // Use - for unordered list bullets (consistent with root config)
+    bullet: '-',
+    // Use --- for thematic breaks (consistent with root config)
+    rule: '-',
+  },
+};
+
+export default config;

lib/platform-bible-react/package.json

@@ -50,8 +50,8 @@
     "format:check": "npm run format:base:check && npm run format:mdx:check",
     "format:base": "prettier --write .",
     "format:base:check": "prettier --check .",
-    "format:mdx": "remark . --use remark-mdx --ext .mdx --output",
-    "format:mdx:check": "remark . --use remark-mdx --ext .mdx",
+    "format:mdx": "remark . --ext .mdx --output",
+    "format:mdx:check": "remark . --ext .mdx",
     "lint": "npm run lint:scripts && npm run lint:styles",
     "lint:scripts": "cross-env NODE_ENV=development eslint --ext .cjs,.js,.jsx,.ts,.tsx --cache .",
     "lint:styles": "stylelint **/*.{css,scss}",

lib/platform-bible-react/src/stories/guidelines/application-interactions.mdx

@@ -10,25 +10,25 @@ Consistent interaction patterns are important for users to feel comfortable and
 
 Platform.Bible embraces the following menu patterns
 
-| Menu          | Description      | Use |
-| ------------- | ---------------- | --- |
-| Main application menu | A [Menubar](https://github.com/paranext/paranext-core/blob/main/lib/platform-bible-react/src/stories/shadcn-ui/menubar.stories.tsx) on the application title bar's start side, that has individual dropdown menus per menu category. This menu hosts all menu items that apply to the application as a whole. | in use |
-| Tab menu | A [Dropdown menu](https://github.com/paranext/paranext-core/blob/main/lib/platform-bible-react/src/stories/shadcn-ui/dropdown-menu.stories.tsx) under a [Hamburger](https://lucide.dev/icons/menu) icon button at the start side of the [Tab Toolbar](https://github.com/paranext/paranext-core/blob/main/lib/platform-bible-react/src/stories/advanced/tab-navigation/toolbar.stories.tsx). This menu hosts all cross-launch and insert related menu entries that relate to the current tab. | in use |
-| Tab view options menu | A [Dropdown menu](https://github.com/paranext/paranext-core/blob/main/lib/platform-bible-react/src/stories/shadcn-ui/dropdown-menu.stories.tsx) under a [Vertical Ellipsis](https://lucide.dev/icons/ellipsis-vertical) button on the end side of the [Tab Toolbar](https://github.com/paranext/paranext-core/blob/main/lib/platform-bible-react/src/stories/advanced/tab-navigation/toolbar.stories.tsx). This menu host options to configure how the current tab should display. | planned |
-| Context menu | A [Context menu](https://github.com/paranext/paranext-core/blob/main/lib/platform-bible-react/src/stories/shadcn-ui/context-menu.stories.tsx), that launches on right click and offers actions in the context of the text or ui part under the cursor | partially used |
-| Text overlay menu | Actions offered next to text selection, without the need to do another right click or the like | idea |
+| Menu                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Use            |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
+| Main application menu | A [Menubar](https://github.com/paranext/paranext-core/blob/main/lib/platform-bible-react/src/stories/shadcn-ui/menubar.stories.tsx) on the application title bar's start side, that has individual dropdown menus per menu category. This menu hosts all menu items that apply to the application as a whole.                                                                                                                                                                                 | in use         |
+| Tab menu              | A [Dropdown menu](https://github.com/paranext/paranext-core/blob/main/lib/platform-bible-react/src/stories/shadcn-ui/dropdown-menu.stories.tsx) under a [Hamburger](https://lucide.dev/icons/menu) icon button at the start side of the [Tab Toolbar](https://github.com/paranext/paranext-core/blob/main/lib/platform-bible-react/src/stories/advanced/tab-navigation/toolbar.stories.tsx). This menu hosts all cross-launch and insert related menu entries that relate to the current tab. | in use         |
+| Tab view options menu | A [Dropdown menu](https://github.com/paranext/paranext-core/blob/main/lib/platform-bible-react/src/stories/shadcn-ui/dropdown-menu.stories.tsx) under a [Vertical Ellipsis](https://lucide.dev/icons/ellipsis-vertical) button on the end side of the [Tab Toolbar](https://github.com/paranext/paranext-core/blob/main/lib/platform-bible-react/src/stories/advanced/tab-navigation/toolbar.stories.tsx). This menu host options to configure how the current tab should display.            | planned        |
+| Context menu          | A [Context menu](https://github.com/paranext/paranext-core/blob/main/lib/platform-bible-react/src/stories/shadcn-ui/context-menu.stories.tsx), that launches on right click and offers actions in the context of the text or ui part under the cursor                                                                                                                                                                                                                                         | partially used |
+| Text overlay menu     | Actions offered next to text selection, without the need to do another right click or the like                                                                                                                                                                                                                                                                                                                                                                                                | idea           |
 
 ## Tab navigation
 
 Tabs can be navigated using keyboard shortcuts:
 
-* `Ctrl + Tab` to move to the next tab
-* `Ctrl + Shift + Tab` to move to the previous tab
+- `Ctrl + Tab` to move to the next tab
+- `Ctrl + Shift + Tab` to move to the previous tab
 
 New Tabs can be opened by
 
-* Pressing the `+` button. This will bring up the `New Tab` dialog on the newly opened tab.
-* Pressing the Home button or selecting any option from the menu that launches a specific new tab.
+- Pressing the `+` button. This will bring up the `New Tab` dialog on the newly opened tab.
+- Pressing the Home button or selecting any option from the menu that launches a specific new tab.
 
 If more tabs are present they will overflow into a menu accessible on hover of the `↕` button.
 
@@ -44,8 +44,8 @@ Floating tabs can be docked back into the main window by dragging and dropping t
 
 Scripture reference selection and displaying is done using the [Book-Chapter-Verse (BCV) control](https://github.com/paranext/paranext-core/blob/main/lib/platform-bible-react/src/stories/advanced/book-chapter-control.stories.tsx). Scripture references can be entered via mouse or keyboard. There is
 
-* a global BCV control on the application title bar - always showing all books
-* an in-tab BCV control on the tab toolbar of every tab that holds Scripture or content relating to some part of Scripture - showing only books of the project in the respective tab
+- a global BCV control on the application title bar - always showing all books
+- an in-tab BCV control on the tab toolbar of every tab that holds Scripture or content relating to some part of Scripture - showing only books of the project in the respective tab
 
 All BCV controls can be used for navigation. Tabs inside Platform.Bible that hold or relate to Scripture content automatically follow the selected new scriture reference.
 
@@ -60,8 +60,8 @@ Examples: Comments, Check Results, Find Results, Footnotes, Occurrences, etc.
 
 Interactions exist in both directions:
 
-* from Scripture Editor: `on Scripture reference change`, `on annotation or caller selection`, `on command / shortcut key press`
-* from list: `on hover`, `on single click`, `on double click`, `on reference click`
+- from Scripture Editor: `on Scripture reference change`, `on annotation or caller selection`, `on command / shortcut key press`
+- from list: `on hover`, `on single click`, `on double click`, `on reference click`
   and respective keyboard interactions
 
 <iframe src="https://embed.figma.com/board/qAjw7U4EcXbi7UDpMwYGsD/Design-System-Content?node-id=1-2&t=QZDawBfx1n2dOTjC-4&embed-host=paratext-design-system" width="100%" height="400" style={{border: "none"}}>

lib/platform-bible-react/src/stories/guidelines/capitalization.mdx

@@ -12,36 +12,36 @@ Sentence case is easier to read and scan quickly. It follows standard English co
 
 ### Examples of sentence case:
 
-* **Buttons**: "Save changes", "Delete item", "Add new project"
-* **Menu items**: "Project settings", "Export data", "User preferences"
-* **Form labels**: "Email address", "Password confirmation", "Project name"
-* **Headings**: "Getting started", "Advanced features", "Troubleshooting guide"
+- **Buttons**: "Save changes", "Delete item", "Add new project"
+- **Menu items**: "Project settings", "Export data", "User preferences"
+- **Form labels**: "Email address", "Password confirmation", "Project name"
+- **Headings**: "Getting started", "Advanced features", "Troubleshooting guide"
 
 ## When to use title case
 
 Use title case sparingly and only for:
 
-* **Product names**: "Platform.Bible", "Paranext"
-* **Proper nouns**: Names of people, places, organizations
-* **API names**: Specific technical terms that are established as proper nouns
+- **Product names**: "Platform.Bible", "Paranext"
+- **Proper nouns**: Names of people, places, organizations
+- **API names**: Specific technical terms that are established as proper nouns
 
 ## Special considerations
 
 ### Abbreviations and acronyms
 
-* Keep established abbreviations in their standard form: "URL", "API", "JSON"
-* Don't force sentence case on well-known technical terms
+- Keep established abbreviations in their standard form: "URL", "API", "JSON"
+- Don't force sentence case on well-known technical terms
 
 ### Brands and external services
 
-* Respect the official capitalization of external brands and services
-* Examples: "GitHub", "YouTube", "macOS"
+- Respect the official capitalization of external brands and services
+- Examples: "GitHub", "YouTube", "macOS"
 
 ### Code and technical terms
 
-* Follow the established conventions of the programming language or framework
-* Component names in React follow PascalCase: `Button`, `DialogContent`
-* CSS classes follow kebab-case: `.search-bar`, `.dialog-overlay`
+- Follow the established conventions of the programming language or framework
+- Component names in React follow PascalCase: `Button`, `DialogContent`
+- CSS classes follow kebab-case: `.search-bar`, `.dialog-overlay`
 
 ## Implementation guidelines
 

lib/platform-bible-react/src/stories/guidelines/component-choices.mdx

@@ -12,46 +12,46 @@ It is an ongoing effort to review and agree on components and variants for commo
 
 For lists and tables, apply the [listbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/examples/listbox-scrollable/) to make it [accessible](#)
 
-* Code: [listbox-keyboard-navigation.hook.ts](https://github.com/paranext/paranext-core/blob/main/lib/platform-bible-react/src/hooks/listbox-keyboard-navigation.hook.ts)
+- Code: [listbox-keyboard-navigation.hook.ts](https://github.com/paranext/paranext-core/blob/main/lib/platform-bible-react/src/hooks/listbox-keyboard-navigation.hook.ts)
 
 For tables, use
 
-* [Table](https://paranext.github.io/paranext-core/platform-bible-react-storybook/?path=/docs/shadcn-table--docs)
-* Data Table
+- [Table](https://paranext.github.io/paranext-core/platform-bible-react-storybook/?path=/docs/shadcn-table--docs)
+- Data Table
 
 For lists, use
 
-* [Item](https://ui.shadcn.com/docs/components/item)
+- [Item](https://ui.shadcn.com/docs/components/item)
 
 Lists may be styled like a single column table **or** as a list of Card-like items.
 
-* See [Result Card](https://paranext.github.io/paranext-core/platform-bible-react-storybook/?path=/docs/basics-resultscard--docs)
+- See [Result Card](https://paranext.github.io/paranext-core/platform-bible-react-storybook/?path=/docs/basics-resultscard--docs)
 
 List entries and table rows may use context menus and [Ellipsis](https://lucide.dev/icons/ellipsis) button to display more options in context of the item under the cursor.
 
 There is a consistent selection and hover style for all lists, that is
 
-* hover: `tw-bg-muted`
-* selected: `tw-bg-muted/50`
+- hover: `tw-bg-muted`
+- selected: `tw-bg-muted/50`
 
 There are consistent interaction patterns for lists, see [Interactions/Scripture editor ↔ Lists](https://github.com/paranext/paranext-core/blob/main/lib/platform-bible-react/src/stories/guidelines/application-interactions.mdx#scripture-editor--lists)
 
 ## Single and multi select options, Filters
 
 Using the
 
-* [Select](https://paranext.github.io/paranext-core/platform-bible-react-storybook/?path=/docs/shadcn-select--docs) component - for simple selections with little options
-* Combobox component - where search, grouping and more details are helpful
-  * [Single Select Combobox](https://paranext.github.io/paranext-core/platform-bible-react-storybook/?path=/docs/basics-combobox--docs): use a [Chevron Down](https://lucide.dev/icons/chevron-down) icon on the trigger, close on selection
-  * [Multi Select Combobox](https://paranext.github.io/paranext-core/platform-bible-react-storybook/?path=/docs/advanced-multiselectcombobox--docs): use the default [Chevrons Up-Down](https://lucide.dev/icons/chevrons-up-down) icon on the trigger, do not close on selection
+- [Select](https://paranext.github.io/paranext-core/platform-bible-react-storybook/?path=/docs/shadcn-select--docs) component - for simple selections with little options
+- Combobox component - where search, grouping and more details are helpful
+  - [Single Select Combobox](https://paranext.github.io/paranext-core/platform-bible-react-storybook/?path=/docs/basics-combobox--docs): use a [Chevron Down](https://lucide.dev/icons/chevron-down) icon on the trigger, close on selection
+  - [Multi Select Combobox](https://paranext.github.io/paranext-core/platform-bible-react-storybook/?path=/docs/advanced-multiselectcombobox--docs): use the default [Chevrons Up-Down](https://lucide.dev/icons/chevrons-up-down) icon on the trigger, do not close on selection
 
 Make sure to
 
-* Show the selection with a start side checkbox (not on the end side like the [default New York style](https://ui.shadcn.com/docs/components/select)) -- up for UX discussion
-* Provide context by using headings and grouping
-* Apply sorting
-* Do not break the default component's focus and hover styles, overflow and grow-shrink behavior (if any, improve it)
-* Single select and multi select Combobox should behave the same - despite selection mode and different icon
+- Show the selection with a start side checkbox (not on the end side like the [default New York style](https://ui.shadcn.com/docs/components/select)) -- up for UX discussion
+- Provide context by using headings and grouping
+- Apply sorting
+- Do not break the default component's focus and hover styles, overflow and grow-shrink behavior (if any, improve it)
+- Single select and multi select Combobox should behave the same - despite selection mode and different icon
 
 <iframe src="https://embed.figma.com/design/hJirMCWP9O9riw39Gd5zyl/Design-System-Figma?node-id=0-1&embed-host=paratext-design-system" width="100%" height="400" style={{border: "none"}}>
   Your browser does not support iframes.