Page MenuHomePhabricator

Add groups to Codex docs sidebar
Open, LowestPublic1 Estimated Story Points


To make the list of components in the sidebar easier to scan/find a component, we have decided to add some component groups. These groups will consist of a name and an expandable section in the sidebar.

The table below outlines the proposed groups and includes known core components that exist in Codex or will be built at some point. Note that there are other components that may be added to Codex in the future, so this is not an exhaustive list. Other groups may be added in the future if a need arises.

Components not yet build in Codex are italicized.

Group nameComponents included
Data displayAccordion, Badge, Card, FilterChip, InfoChip, Menu, MenuItem, Popup/Popover, Table, Tooltip
FeedbackDialog, Message, ProgressIndicator, ProgressBar, Skeleton, ToastNotification, ValidationMessage
Input & ControlsButton, ButtonGroup, Checkbox, Combobox, Field, FileInput, Label, Lookup, NumberInput, Radio, Select, Textarea, TextInput, ToggleButton, ToggleButtonGroup, ToggleSwitch
MediaIcon, Image, Thumbnail
NavigationLink, Tab, Tabs
SearchSearchInput, TypeaheadSearch

Acceptance criteria
  • Ask team for final feedback on initial groups implementation
  • Implement groups on VitePress site

Event Timeline

That's great for orientation. Really looking forward to see this live.

One detail, have shared this in the document: Are we majority-set on “Chips”? Chips are potato chips at best in German, and mostly referred to as circular things (poker chips), not rectangular rounded things, like our “chips”, err “pills”.

@Volker_E I don't think we're 100% set on that name—since those components haven't been designed or built yet, we don't have to add a group in the sidebar for them at the moment.

Change 805910 had a related patch set uploaded (by Anne Tomasevich; author: Anne Tomasevich):

[design/codex@main] [WIP] docs: Refactor site hierarchy to add component groups

Moving this to the sprint to work on while blocked on higher priority tasks.

Change 831151 had a related patch set uploaded (by Anne Tomasevich; author: Anne Tomasevich):

[design/codex@main] [WIP] Add component groups

AnneT changed the task status from Open to In Progress.Sep 9 2022, 9:37 PM
AnneT updated the task description. (Show Details)

@Sarai-WMDE @Volker_E @egardner and (@Catrope if he has time), I've updated the task description to include the latest iteration of the component groups that we've been developing here. You can also review a demo of these groups.

Here is some important context:

  • The purpose of the groups is to make it easier for people to find components and to help people form a mental map of components and how they relate to each other
  • Per feedback from Codex stakeholders, we have tried to group components based on what they do, not what they are or how they are implemented. The impact of this feedback included moving various button components to Inputs & Controls, removing the Menu and Tabs groups in favor of putting those components in groups that describe their function, and moving all components into groups (rather than having some of them outside of any group). We hope this will help people find a component that they don't know the exact name of, but know the general function they're looking for.
  • We aim to keep the groups somewhat consistent with each other (e.g. describing a function or set of functions, short descriptive group names)

Do you have any feedback on the component groups and their names? I'm hoping we can finalize this this week!

I'd consider moving Tabs to Layout.

That makes sense to me, and I think Accordion might be considered layout as well

Moving both Tab/Tabs and Accordion to Layout sounds good 👍 Many systems classify Tabs as navigation, but that's theoretically incorrect. I guess the upcoming Stepper and Pagination components would then belong into Layout rather than Navigation too.

Just for visibility, Anne and I are also having a parallel conversation regarding Dialog here.

I'm having a hard time with most grouping in other Design Systems, particularly when the doc site doesn't feature a fuzzy search. It's nearly everywhere finding yourself in some other person's/group's definition that you need to invest time to learn and orient. There are too often differences (already starting at the component's names, see my favorite example tags, that is here represented as chips) and no real standards across the globe.

One vocal example in the current list would be SearchInput. I stopped skimming the groups and immediately went into “Inputs and Controls” to search for it. Just to have to search further to discover a separate “Search” group.
Also, to come from a general usability rule of thumb, don't group if there are only two members.

I'd put forward another proposal: Let's not group the components (as long as we're not providing search).

I'd put forward another proposal: Let's not group the components (as long as we're not providing search).

Fair enough. I find the functional grouping really strong and sensible, but at the same time I wouldn't like us to provide a classification that keeps raising concerns and feeling arbitrary to any degree. I would encourage us to keep exploring grouping options internally but, if you all concur, we could delay this decision until search is available (strongly agreeing with that point). Pinging @Sgs for visibility.

AnneT changed the task status from In Progress to Stalled.Sep 15 2022, 9:17 PM
AnneT removed AnneT as the assignee of this task.

We've decided to pause this work for now, acknowledging that we should do the following before implementing groups in the sidebar:

  • Enable search on the docs site (T317792)
  • Do a working session with designers to improve component groupings

For now, we have few enough components that a single list in the sidebar isn't overwhelming. We do think there is value in adding groups in the future, though, so we'd like to pick this back up when we can.

ldelench_wmf set the point value for this task to 1.Sep 19 2022, 3:37 PM
ldelench_wmf changed the task status from Stalled to Open.Jan 20 2023, 7:07 PM
ldelench_wmf lowered the priority of this task from Low to Lowest.