docs(demo): rewrite the Nav page around choosing a pattern by matthewmr-eqty · Pull Request #211 · eqtylab/equality

matthewmr-eqty · 2026-10-30T20:11:02Z

Review focus

Stacked on #210: review only the last commit, docs(demo). No release; merging redeploys the docs site.

Need

People and agents building a sidebar need to know when a row drills, expands or switches, and the rules to follow.

Problem

The Nav page stated the drill rule six times and never said when to expand. It had no folders, new-tab links or phone layout, and its rules mixed demo pairs with loose bullets.

Change

Opens with "Which One to Use": five rows, each linked to its section.
Adds folders, nested folders, a full app sidebar, a docs sidebar built from a tree, the sidebar in a phone Sheet, and new-tab links.
Ends with Best Practices, one heading per rule, so a lint error can link to its reason. Rules TypeScript already enforces are cut.
The agent skill points at Best Practices.

Rules beside each section were rejected: rules that span parts had no home.

Evidence

astro check, lint and Prettier pass.
Blind evals of the page's Markdown copy with cold agents: the first rewrite was 26% shorter with fewer guesses at equal scores. The final page scored 17 and 18 of 18, with topic guesses down from 13 to 7.

Not covered

Two runs per eval. The latest runners used Sonnet; the earlier runners' model is unknown. Gaps the eval still found: one example mixing router rows, an external row and a badged folder; a rule for a few flat pages; one page per item, such as a members list.

Part of GRD-193 · GRD-81

🤖 Generated with Claude Code

Need: People and agents building a sidebar need to know when a row drills, expands or switches, and the rules to follow. Problem: The page stated the drill rule six times and never said when to expand instead. Solution: It opens with a "Which One to Use" table, shows full app, docs and phone sidebars, and ends with Best Practices, one heading per rule. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Need: Screen reader users jump between landmarks by name. Problem: The Nav page showed three panels called "Project: Ben Project" and two rails called "Main". Solution: The second app sidebar and the Switcher demo name themselves as examples. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Shrinks99 · 2026-10-30T20:58:20Z

+| You want to                                                           | Use                          | For example                                       | Not for                                                                    |
+| --------------------------------------------------------------------- | ---------------------------- | ------------------------------------------------- | -------------------------------------------------------------------------- |
+| Go to a page                                                          | [A row in a group](#groups)  | Dashboard, Indicators                             | Actions, such as Log out: use a [Dropdown Menu](/components/dropdown-menu) |
+| Change to another one of the thing you're in                          | [`NavSwitcher`](#switcher)   | Another project                                   | Filtering a page: use a [Select](/components/select)                       |


This description is too generalized, and could easily apply to Tabs

Suggested change

| Change to another one of the thing you're in | [`NavSwitcher`](#switcher) | Another project | Filtering a page: use a [Select](/components/select) |

| Navigate between objects that apply to the current application's section | [`NavSwitcher`](#switcher) | Another project | Filtering a page: use a [Select](/components/select) |

Shrinks99 · 2026-10-30T20:59:36Z

+| --------------------------------------------------------------------- | ---------------------------- | ------------------------------------------------- | -------------------------------------------------------------------------- |
+| Go to a page                                                          | [A row in a group](#groups)  | Dashboard, Indicators                             | Actions, such as Log out: use a [Dropdown Menu](/components/dropdown-menu) |
+| Change to another one of the thing you're in                          | [`NavSwitcher`](#switcher)   | Another project                                   | Filtering a page: use a [Select](/components/select)                       |
+| Go into something with its own pages, where other rows stop mattering | [Drill in](#drill-in)        | A policy, an agent's run, an app's Settings pages | A few views of one screen: use [Tabs](/components/tabs)                    |


Suggested change

| Go into something with its own pages, where other rows stop mattering | [Drill in](#drill-in) | A policy, an agent's run, an app's Settings pages | A few views of one screen: use [Tabs](/components/tabs) |

| Navigate into a sub-section with its own pages, where other rows in the current section stop mattering | [Drill in](#drill-in) | A policy, an agent's run, an app's Settings pages | A few views of one screen: use [Tabs](/components/tabs) |

Shrinks99 · 2026-10-30T21:00:04Z

+| Change to another one of the thing you're in                          | [`NavSwitcher`](#switcher)   | Another project                                   | Filtering a page: use a [Select](/components/select)                       |
+| Go into something with its own pages, where other rows stop mattering | [Drill in](#drill-in)        | A policy, an agent's run, an app's Settings pages | A few views of one screen: use [Tabs](/components/tabs)                    |
+| Browse pages grouped by topic                                         | [Expand](#expandable-groups) | A docs site's folders, at any depth               | An area people work inside: [drill in](#drill-in)                          |
+| Move between an app's largest areas                                   | [`NavRail`](#usage)          | Projects, Agents, Library                         | An app with one area                                                       |


Shrinks99 · 2026-10-30T21:24:46Z

-## Drill-in
+## Switcher
+
+`NavSwitcher` goes in the panel's `header` and shows the current item's name. Picking another item calls `onValueChange`, and your app goes to that item's top level. A level drilled into, such as a policy, belonged to the old item, so don't carry it across. `action` adds a command at the foot of the list.


A level drilled into, such as a policy, belonged to the old item, so don't carry it across.

There's gotta be a clearer way of saying this?

"Level names should not be displayed on the back button, instead use the name of the previous subsection" perhaps?

Shrinks99 · 2026-10-30T21:26:50Z


+## Best Practices
+
+### Pages, Not Actions


Suggested change

### Pages, Not Actions

### Use Nav for Pages, Not Actions

Shrinks99 · 2026-10-30T21:27:46Z

+
+Every row takes the reader somewhere. Put actions elsewhere: Log Out in a [Dropdown Menu](/components/dropdown-menu), Create Project in the switcher's `action`. A reader who clicks a row expects to go somewhere, not to change something.
+
+<NavListDemo client:only="react" variant="do-dont-actions" />


Do we need demos for these? They won't show up when the page is rendered to .md and LLMs won't read them.

Shrinks99 · 2026-10-30T21:29:07Z

+
+### Don't Restyle Rows
+
+A row with its own colours or sizes reads as an error, or as a different control. To change every row on a site, set the `--eq-list-item-*` variables.


Suggested change

A row with its own colours or sizes reads as an error, or as a different control. To change every row on a site, set the `--eq-list-item-*` variables.

A row with its own colours or sizes reads as an error, or as a different control.

I think we shouldn't tell agents to do this

matthewmr-eqty added this pull request to stack #213 October 30, 2026 20:12

matthewmr-eqty mentioned this pull request Oct 30, 2026

feat(docs): release 0.16.0 with a sidebar built from Equality's Nav parts #212

Open

matthewmr-eqty requested review from Shrinks99 and tmccoy14 and removed request for Shrinks99 October 30, 2026 20:18

matthewmr-eqty marked this pull request as draft October 30, 2026 20:41

matthewmr-eqty marked this pull request as ready for review October 30, 2026 20:53

matthewmr-eqty and others added 2 commits October 30, 2026 16:54

matthewmr-eqty force-pushed the docs/grd-193-nav-page branch from 71ef7b4 to 64d3480 Compare October 30, 2026 20:54

Shrinks99 requested changes Oct 30, 2026

View reviewed changes

Navigation Menu

Repository navigation

docs(demo): rewrite the Nav page around choosing a pattern - #211

docs(demo): rewrite the Nav page around choosing a pattern#211
matthewmr-eqty wants to merge 2 commits into
feat/grd-193-nav-expandablefrom
docs/grd-193-nav-page

matthewmr-eqty commented Oct 30, 2026 •

edited

Loading

Uh oh!

Shrinks99 Oct 30, 2026

Uh oh!

Shrinks99 Oct 30, 2026

Uh oh!

Shrinks99 Oct 30, 2026

Uh oh!

Shrinks99 Oct 30, 2026

Uh oh!

Shrinks99 Oct 30, 2026

Uh oh!

Shrinks99 Oct 30, 2026

Uh oh!

Shrinks99 Oct 30, 2026

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	\| Change to another one of the thing you're in \| [`NavSwitcher`](#switcher) \| Another project \| Filtering a page: use a [Select](/components/select) \|
	\| Navigate between objects that apply to the current application's section \| [`NavSwitcher`](#switcher) \| Another project \| Filtering a page: use a [Select](/components/select) \|

	\| Go into something with its own pages, where other rows stop mattering \| [Drill in](#drill-in) \| A policy, an agent's run, an app's Settings pages \| A few views of one screen: use [Tabs](/components/tabs) \|
	\| Navigate into a sub-section with its own pages, where other rows in the current section stop mattering \| [Drill in](#drill-in) \| A policy, an agent's run, an app's Settings pages \| A few views of one screen: use [Tabs](/components/tabs) \|

	\| Move between an app's largest areas \| [`NavRail`](#usage) \| Projects, Agents, Library \| An app with one area \|
	\| Move between an app's largest sections \| [`NavRail`](#usage) \| Projects, Agents, Library \| An app with one area \|


		Every row takes the reader somewhere. Put actions elsewhere: Log Out in a [Dropdown Menu](/components/dropdown-menu), Create Project in the switcher's `action`. A reader who clicks a row expects to go somewhere, not to change something.

		<NavListDemo client:only="react" variant="do-dont-actions" />


		### Don't Restyle Rows

		A row with its own colours or sizes reads as an error, or as a different control. To change every row on a site, set the `--eq-list-item-*` variables.

Conversation

matthewmr-eqty commented Oct 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review focus

Need

Problem

Change

Evidence

Not covered

Uh oh!

Shrinks99 Oct 30, 2026

Choose a reason for hiding this comment

Uh oh!

Shrinks99 Oct 30, 2026

Choose a reason for hiding this comment

Uh oh!

Shrinks99 Oct 30, 2026

Choose a reason for hiding this comment

Uh oh!

Shrinks99 Oct 30, 2026

Choose a reason for hiding this comment

Uh oh!

Shrinks99 Oct 30, 2026

Choose a reason for hiding this comment

Uh oh!

Shrinks99 Oct 30, 2026

Choose a reason for hiding this comment

Uh oh!

Shrinks99 Oct 30, 2026

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

matthewmr-eqty commented Oct 30, 2026 •

edited

Loading