Page MenuHomePhabricator

Define core components
Closed, ResolvedPublicSpike


This task is now obselete and will get outdated; see the current list of planned components on



As a potential user of Codex, I want access to a robust set of consistent, accessible, usable components to help me build a better UI

As a potential user of Codex, I want to know which components I can expect to have access to if I decide to use Codex

As a user of Codex, I want access to commonly used components so I don't have to build them myself or delay a project while I wait for a component to be built

As a user of Codex, I want to understand the status of commonly used components so that I know how it will impact my work

The Design Systems Team would like to provide a list of core components to inform potential and current users of Codex about which components we plan to build and the status of those components.

A core component is a commonly used component that we almost certainly intend to add to Codex at some point. Some core components have already been designed and built, some are high priority, and some are lower priority, but they are all components that we will most likely add to Codex at some point. These components may be designed and built by the Design Systems Team or by other contributors to Codex.

Note that we have also identified a number of non-core components: these are components that have been identified as potential Codex components, but have not yet been prioritized for various reasons. Some of these components have only been used in one place and do not yet need to be sharable, some of them require a lot of design conversations before they can be scoped, and some of them are just ideas that don't have a solid use case yet.


We aim to propose a list of core components based on our own research and discussions, then share this list with other front-end contributors for review and feedback. At the end of this feedback period, we will document the list of core components. This list does not need to be absolutely final: it could be altered in the future if we decide a component no longer qualifies as a core component, or if we identify a new core component that we want to add to the list.

Acceptance criteria
  • Design System Team to propose a list of core components, documented in this task
  • DST to share this list with other front-end contributors to collect feedback
  • DST to incorporate that feedback and update the list
  • DST to post the list somewhere public and non-ephemeral (i.e. not a Phab task)

Proposed planned critical components

Important notes:

  • Component names are not necessarily final (e.g. "chip" vs. "tag"), but these are the working names that we're using
  • Relevant links are meant to offer more information about what each component is. That's a Codex demo page, a Design Style Guide page, or a Phab task, depending on what's available.
ComponentDescriptionStatus in CodexRelevant link
AccordionExpandable and collapsible layout In progressT326665
BadgeSmall indicator of status or countNot startedT280708
ButtonControl that specifies the action that will occur when a user clicks on it DoneDemo
ButtonGroupSet of actions made up of two or more buttons DoneDemo
CardLayout for grouping information and actions related to a single topic DoneDemo
CheckboxBinary input that can be standalone or in a multiselect group DoneDemo
ChipInputInput for selecting filter chipsNot startedT280701
ComboboxAutocomplete text input with an expandable menu of predefined items DoneDemo
DialogModal element that presents relevant information or actions In progressT284838
DividerVisual division of sections within a page or between components In progressT300659
FieldForm field with a label, an input or control, and validation handlingNot startedT309239
FileInputInput for selecting and submitting a fileNot startedDSG
FilterChipInteractive chip that can be selected, removed, or generated from an inputNot startedT322524
IconSmall graphical representation of an idea DoneDemo
ImageImage display with sizing and fallback support optionsNot startedT314514
InfoChipNon-interactive chip that provides informationNot startedT322524
LabelDescribes the information requested by a given form fieldNot startedT309246
LinkTextual element used to navigate between sections or pages In progressT309248
LookupPredictive text input with a dropdown menu of items DoneDemo
MenuContextual list of selectable options, often triggered by a control or an input DoneDemo
MenuItemA selectable option included within a Menu DoneDemo
MessageSystem feedback in response to or to inform a user action DoneDemo
NumberInputInput for entering a numberNot startedT330101
Popup/PopoverSmall, contextual overlay that displays additional information or actions when hovering over, focusing or tapping on an element.Not started
ProgressBarLinear indicator of progress Partially doneDemo
ProgressIndicatorAnimated signal that a process is occurringNot startedT266028
RadioBinary input part of a single-select group DoneDemo
SearchInputInput for text search with optional button DoneDemo
SelectInput with a dropdown menu of predefined selectable items DoneDemo
SkeletonPlaceholder layout for content that hasn’t loaded yetNot startedT311874
TableStructure categorical information in rows and columns in order to facilitate the comparative analysis of dataNot startedT303320
TabsLayout for navigating between sections of content DoneDemo
TabRepresents a section of content within a Tabs layout DoneDemo
TextareaMulti-line text input that allows manual resizing In progressT284272
TextInputForm element that let users input and edit single-line values in the form of text DoneDemo, T293271
ThumbnailSmall preview of an image DoneDemo
ToastNotificationTemporary pop-in feedback messageNot startedT303612
ToggleButtonButton that can be toggled on and off DoneDemo
ToggleButtonGroupGroup of toggle buttons for making a selection DoneDemo
ToggleSwitchSliding boolean input, generally used to enable/disable options DoneDemo
TooltipFloating label with a short description of a user interface elementNot startedT280677, T312899
TypeaheadSearchSearch input that provides a menu with autocomplete suggestions DoneDemo
ValidationMessageFeedback on form input validityNot started

Identified non-core components and patterns

These are the components and patterns we've discussed but decided not to include as "core":

Avatar, Breadcrumbs, button with dropdown (the button can either display a contextual navigation menu, allow selection and reflecting it, and/or allow users to make an action upon selection – e.g. "Download small/medium/large size" button with dropdown), Carousel, ChipInput/TagInput, ColorPalette, ColorPicker, data visualizations, DatePicker, DateTimeInput, Diff, drag & drop/teorder, EmptyState, FloatingButton, Grabber/Handlebar, ImageGallery, language selectors, List, lists of pages, media player controls, navigation menu, offline states, page previews, page/view types, Pagination, PulsatingDot, Sheets, Slider, Stepper, text highlight

Related Objects

Event Timeline

There are a very large number of changes, so older changes are hidden. Show Older Changes

@Sarai-WMDE please feel free to edit the task description or add anything else that you think is important here!

@AnneT @Sarai-WMDE should we add Thumbnail in this list? Although we already have it in Codex I'm not sure if it's a core component or not.

Apart from thumbnail I think a good candidate to be in the core component list would be the Image component (defining its sizes, aspect ratios and states). Do we plan to add Image as component?

@bmartinezcalvo good call! I think we may as well add Thumbnail since it already exists. I could see Image being useful (we had an Image component in structured data projects that also lazy-loaded the image once it came into the viewport), but we haven't discussed it as a team yet.

I think this list correctly reflects our known core components. Thank you, @AnneT!

I wonder what we should do about: 1. potential core components that we're not fully aligned on yet (e.g. Image – would be pro adding it to the list–, Accordion/Expand, Carousel, List, Pagination...) and 2. important patterns that will probably be developed as mixins (e.g. Divider, Label, Skeleton).

I'd personally add the latter to the list (with an indication of their actual nature). About the former (core component candidates), I would probably mention their existence, and link to the ticket where they are publicly listed: T277047 (I can update the table to reflect core/ core candidate components).

For potential components we're not aligned on, I would recommend leaving them off of the list of core components, which I see as components we are almost definitely going to build at some point. Really, the list might already be too long at this point :) Perhaps we can reference the design inventory table to indicate that we have a longer list of potential but not core components?

For important patters that we're likely to include, I think we should include them in the core list somehow since we have the same goal of informing consumers of Codex that these things will be available to them at some point—maybe as a separate list called core mixins or core patterns?

Perhaps we can reference the design inventory table to indicate that we have a longer list of potential but not core components?

Exactly! That's all I meant we should do.

Maybe as a separate list called core mixins or core patterns?

Sounds good! :)

I think an Image component is worth adding to the core list here.

We also may want to consider a Video component or multi-media component. Some prior art exists in MediaSearch for this.

These components could handle things like lazy-loading or loading indicators, fallbacks for broken links, responsive images, etc.

The epic T277047: Design inventory of Wikiverse (Codex design system, OOUI, MediaWiki widgets) UI components was updated to reflect the list of core and potentially core Codex components. For now, and until we reach some consensus, both Image and Media player components were documented as the latter.

I'm fine with adding those components in the core components list and also one more:

  1. Image (single image component)
  2. Image gallery (group of images). This could be specially useful for Wikimedia Commons)
  3. Video player
ldelench_wmf changed the task status from Open to Stalled.Aug 14 2022, 11:29 PM
ldelench_wmf moved this task from Inbox to Needs Refinement on the Design-System-Team board.
DAbad changed the task status from Stalled to In Progress.Aug 22 2022, 5:27 PM
DAbad assigned this task to AnneT.
DAbad changed the subtype of this task from "Task" to "Spike".

August 22, 2022 Task Refinement:

  • what is the scope of this: supporting for new features vs migrating legacy
  • How do we get to done?
    • Maybe need to define what a "core component" is
      • when is this ready for use
      • this should align with other design systems
        • look at a list of common components in major design systems (we should overlap)
  • what have we done so far:


  • Add the following Acceptance Criteria
    1. Pull in historical usage of components into a single master view of suggested core components
      • Add a one-liner describing each component (link to samples also helpful)
    2. Review general standard components for other design systems (1-2)
    3. Survey other teams for what they deem as core components - we will set a due date to get this feedback

Two questions from me for the design team (@Volker_E @bmartinezcalvo @Sarai-WMDE):

  1. Is there anything I can link to for InfoChip?
  2. What's the difference between Popup/Popover and Tooltip?

I would suggest that if a component is so important to the design system that it's a "core component", we (DST) should build it ourselves (or at least an initial version of it), rather than waiting for a team to need it and then have them work with us to build it. That suggests to me that we should trim this list a bit. I think we all agree that Button and Dialog are core components that it makes sense for DST to build, but what about DatePicker and FileInput for example? Or maybe we can split the list in tiers, and only commit to building components in the top tier ourselves?

Two questions from me for the design team (@Volker_E @bmartinezcalvo @Sarai-WMDE):

  1. Is there anything I can link to for InfoChip?

I had to read through all comments in T280681 to understand what's meant with “InfoChip”. A tag is exactly that widely used term for filtering and categorizing information. The separation here is interactive or just informative. Wonder if we need to provide both, I'd like to see them as one component. Altogether we should settle as team soon on one name and use it consistently, the tag/pill/chip bs – see also T280681#7720967 for weirdness in other design systems – is haunting me at night.

  1. What's the difference between Popup/Popover and Tooltip?

Not sure if it is appropriate to separate them. A tooltip should not show interactive content, while a Popup could potentially contain such. The view logic should be the quite similar (with maybe show/hide and focusability differences).

TimeInput is currently missing here, or we rename DateInput to DateTimeInput to incorporate this functionality.

Dialogs come in so many different flavors, that I would rather see them split it up into sub-types similar to Buttons.
To compare with OOUI – message dialogs, simple dialogs, process dialogs.

@AnneT thank you for collecting all the core components list in the task. I've reviewed them and I'm commenting here some that are missing:

  • Tag input: we have it in the OOUI Figma spec and in the OOUI demo
  • Loader indicators (Spinners, Bouncing dots): should we include them as core components?

@bmartinezcalvo, in relation to your last comment:

Tag input: we have it in the OOUI Figma spec and in the OOUI demo

I think this would be ChipInput, based on the new terminology

Loader indicators (Spinners, Bouncing dots): should we include them as core components?

Those would be ProgressIndicator(s).

Regarding your questions, @AnneT :

  1. Is there anything I can link to for InfoChip?

Not for now. I think there's only a generic task about adding the Chip component to Codex for now (T309249). We should create a specific task for InfoChip. If I'm not mistaken, this variant of Chip will be needed by Abstract Wikipedia.

  1. What's the difference between Popup/Popover and Tooltip?

Popoup/Popovers (generally white boxes with pointers) can contain a greater amount of information and even media and actions. Tooltips (usually with a dark background) are smaller, generally only triggered on hover. They provide very short, clarifying information. I think the latter were defined recently in the context of Abstract Wikipedia. As noted in the original spreadsheet, these sound too much like the default browser tooltips, so we might need to clarify if we're talking about customizing those. Edit: This lack of definition might be a reason to document Tootltips as Potential core components instead?

Thanks, all! After reading through the comments, I'd like to make the following suggestions:

  • We follow Roan's suggestion of thinking of core components as ones that would make sense for DST to build. That doesn't mean we have to build every one, but it's helpful to distinguish between components that have many use cases across projets and components with only one or two use cases/projects.
  • We update DateInput to DateTimeInput as Volker suggested, but we consider removing it since it's pretty Wikidata-specific (it's also used on the structured data tab of filepages, but that's also Wikidata-specific)
  • We consider removing any other components that seem more specific to a single project/use case. Diff would be another candidate for removal.

Also, based on conversation with Sarai, we may want to add Accordion (aka expand/collapse)

  • We consider removing InfoChip if it's specific to one project (if not, it can stay)

I wouldn't remove the InfoChip from the core components list since chips are being used in some projects and in each one of these design projects the chip is being designed differently since we don't have any guidelines defined for this component.

I would consider to include this component in the list since it's a component we need to define in depth.

@bmartinezcalvo sounds good, thanks for the info! I'll remove that suggestion.

AnneT updated the task description. (Show Details)

Assigning to Sarai to add a comment about the other libraries she's reviewed!

The initial list of core components included in this ticket is based off of the design inventory of the Wikiverse performed by the product design team at WMF. We applied the following criteria to extract potential core components from said list:

  1. Recurrent use in several of our projects (e.g. Message. This resulted in omissions such as that of 'Carousel'). In most cases, said components are already present in our existing UI libraries (OOUI, WVUI or WiKit) and require a migration.
  2. Correspondence with HTML form and interactive elements (e.g. <button>, <dialog>, <input> with its different types, <select>, etc…)
  3. Parity with popular, mature design systems. This is the least crucial or leading criterion, as we should always prioritize covering our particular use cases. Nevertheless, their existence in other libraries allowed justifying the introduction of certain detected components and patterns (e.g. skeleton loading) and can help us standardize some of our idiosyncratic elements. For reference, the following two resources provide an overview of common building block across external design systems: The component gallery, Open UI.

Based on this criteria (specially the first one), I would suggest a first update that removes ChipInput, Floating button and DatePicker (vs DateInput) from the list. Since the extension of their use case is unclear.

I think once we decide this, the list will be ready to be evaluated and adjusted with help from our collaborators. Hopefully, feedback will allow us to refine it in accordance to the first criterion.

In parallel to this, I believe that the DST should start defining how non-core components will be handled. These might be required, single-use Vue components that are project-specific (such as "Input with expander" in Wikidata/Wikibase). It'd be great to define an approach as to how these are related to our core components, a where will these be located.

Thanks for this helpful information, @Sarai-WMDE! I've also removed FloatingButton, ChipInput, and DatePicker from the list of core components based on your suggestion.

Reading the task description it seems (to me and maybe I’m reading wrong), the main characteristic of a component to be part of “core” is its certainty to be added to the library which is a derivative from how commonly it is used. The second characteristic would be that DST team will work on it or it will be prioritized in general.

From an outsider UI library consumer “core” resonates to “basic”, “blueprints”, “atoms” of a wider UI system which allow to build more complex components as opposite of when or who will implement the component. Mind that I'm not native-english speaker and this is just about nomenclature/naming.

I like better the "tiers" concept @Catrope suggested. Maybe scoring how atomic a component is (depends on other components or design tokens) and how critical to implement (other components depend on it, urgent, commonly used across MW software, product request) and based on the final score assign it to tier 1, 2..N. DST can focus on tier 1 then.

I like very much to see some sense of component groups/categories. I’d suggest to use a taxonomy focusing on “what” the component does (function, action, motion) rather on how it looks (shape). Some UI libraries that group components by function: Ant design, React Matrial UI (MUI), Chackra UI. For instance, messages (Message, ToastNotification) and progress groups would belong to the "Feedback" category whereas ValidationMessage belongs to the "Forms/Data Entry" category.

I really miss a Layout group/category with components like Grid, Container, Flex, Box, Stack, Wrap… which serves as a the scaffolding base components for higher level components enforcing some commons. For instance one could build a Card with a Box or more.

Maybe a Typography category for handling font commons, headings, etc. is worth considering (ie Chackra UI Text component ). Having Layout and Typography components using Codex design tokens could help to minimize the Don't rely on px unit based values problem.


suggestion: change naming of "core" to tiers (1,2...) based on component dependency tree and how critical it is.
suggestion: use functional category names and re-organize list
suggestion: create a Layout category for common scaffolding, composition and elements gutter
suggestion: create a Typography category for common text display
nit: Field and Label component seem strictly related to the category input & controls (Forms, data entry).
nit: Buttons could be under input & controls, they are a control afaiu

Hey @Sgs 👋🏻 I think your suggestions are really on point. I went ahead and tried to adjust our list using this spreadsheet to:

  1. Drop the concept of "core" and instead categorize components by tiers (1, 2, 3). This is a first assessment (based on how atomic and essential the components are), and will need further polishing. Yours and DST's feedback here would be really welcome 🙏🏻
  1. Use functional category names to group components: this is an excellent approach that brings a lot of order and meaning to the categorization. It prevents us from leaving any components ungrouped (see "Other core components").
  1. Includes Label and Buttons under "Inputs & controls".

Regarding Typography and Layout (Grids): Our initial plan was to group such "foundational" elements under a global category that's separate from components. This category could be named something like "Global styles" or "Visual foundations". I think that separation makes a lot of sense when it comes to typographic styles and grids, but I do agree that documenting reusable "utils" such as box* under such "Layout" category makes a lot of sense. I included said category in the list. (But left Typography out in this first iteration).

*Box/frame only exists as a design concept for now. I'll need to align with the rest of the team to decide if we want to reuse and document such agnostic building blocks.

Thanks again for the great input!

Huge +1 to the functional group names, this is a major improvement toward our goal of using groups to make components easier to find and mentally map.

The atomic design tiers are helpful to us in terms of defining Codex's architecture, but I think the main goal of this task could still be served by naming the set of components we intend to prioritize because they have multiple use cases. Perhaps we can find a way to present the following information:

  • For people who just want to know what components we intend to build, we provide a simple list of "core" components (or some other name that is more clear)
  • For people with a deeper understanding of design system architecture who want more granular knowledge, we provide the tier data

I've updated the list in the task description to remove the component groupings, so this particular task can focus on the list of components and not the organization of that list. Further discussion specific to component groupings can happen in T309109.

@Sarai-WMDE and I have collected feedback here and in 1:1 channels. We met to come up with a final proposal for this, outlined below.

Provide a list of "planned components"

We'd like to propose changing the name of this list from "core components" to "planned components." "Core" does not necessarily have a clear meaning, and we feel that providing a list of planned components will help meet the goal of informing Codex users about what we intend to provide in the library.

Planned components are components that we definitely plan to include in the library because they fit one or both of these criteria:

  1. They are a critical "atom" component, or a component that will be used within other components as a building block
  2. They have multiple use cases across our products (i.e. more than one use case)

This list is not static: if we identify another component that has multiple use cases, we may add it to the list of planned components. If a feature team or volunteer has built a component for a specific project, then another use case is identified, that component might be added to the list of planned components. All that said, the current list in the task description includes all the components we've identified so far that meet the criteria.

Initial list of planned components

The list in the task description is our proposal for the initial iteration of this list.

Post list of planned components plus other potential components

We've identified and discussed a number of components not on the list of planned components. We should include a list of these along with the list of planned components, so that users of Codex are aware of the discussions we've already had about these components, and can provide additional use cases if they exist. This will also help us keep track of project-specific components built by feature teams or volunteers that we might want to add to Codex one day if we identify a need to share those components.

In a future task, evaluate priority of planned components

Sarai suggested that we create a "scorecard" system with various criteria for evaluating the priority of each component on the planned components list. This could include things like whether the component is a building block for other components, how many use cases we've identified, etc. This would be an objective way of evaluating how important each component is and creating a priority order for component work. We could come up with a series of priority tiers if we feel that helps clarify components' classifications. Once this work is done, we could include each component's score or tier in the table representing the planned components list.

@DAbad please let us know if you have any feedback!

Noting that we added ChipInput back in because FilterChips require a chip input, and because there are multiple use cases for it.

@DAbad is it possible for us to "finalize" this as we're preparing for the roadshow ("finalize" being in quotes because this isn't set in stone)? I'm imagining posting this list with a brief explanation of what it is on, and linking to that list on the Codex docs site. What do you think? I'm happy to create a subpage of our team page on and draft the explanation and transfer the table of components there.