Page MenuHomePhabricator

Increase specificity when styling subcomponents
Closed, ResolvedPublic5 Estimated Story Points



Per T344021#9312795, we need to:

  • Create and document a standard in the library where we always add specificity when styling a subcomponent
  • Add the subcomponent's class as an additional class selector.

Concretely, the latter means that when there's e.g. an Icon component inside the Label component, the Label component currently styles it with &__icon (which expands to .cdx-label__icon), but instead of that we want it to use &__icon.cdx-icon (which expands to .cdx-label__icon.cdx-icon).

See T344021#9312795 for an inventory of which components use which other components (also duplicated in the acceptance criteria below).

Acceptance Criteria

  • Document this standard
  • Apply it to all components
    • Accordion: Button, Icon
    • ButtonGroup: Button
    • Card: Icon, Thumbnail
    • Checkbox: Label (via binary-input.less)
    • Combobox: Button, Icon, TextInput
    • Dialog: Button
    • InfoChip: Icon
    • InputChip: Button
    • Label: Icon
    • Lookup: TextInput
    • Menu: MenuItem, ProgressBar
    • MenuItem: Icon, Thumbnail
    • Message: Button, Icon
    • Radio: Label (via binary-input.less)
    • SearchInput: Button, TextInput
    • Select: Icon
    • Tabs: Button (cdx-tabs__list__item)
      • Remove cdx-tabs__list__item because this selector is applied to a static HTML <button> - not a CdxButton.
      • Apply specificity to the scroll button (cdx-tabs__scroll-button) which is a CdxButton.
    • TextArea: Icon
    • TextInput: Icon
    • Thumbnail: Icon
    • ToggleButtonGroup: ToggleButton
    • ToggleSwitch: Label
    • TypeaheadSearch: Icon, MenuItem, SearchInput


Instructions to test local Codex changes in a MediaWiki instance


  • Open 3 separate editor windows (VSCode) that cd into these repositories: MediaWiki, CodexExample, and Codex
  • Run an instance of MediaWiki (instructions found in MediaWiki repo
  • Install CodexExample extension in MediaWiki
  • Use this CodexExample playground branch
    • In CodexExample, checkout the branch by running git checkout css-specificity-staging


  1. Make changes in the Codex repo
  2. In Codex, run npm run -w @wikimedia/codex build to create an optimized production build of Codex. The build process output is stored in /dist/modules/.
  3. In MediaWiki core, run cp ../codex/packages/codex/dist/modules/* resources/lib/codex/modules/to copy the files from Codex to MediaWiki core. This copies the local changes from Codex into your local MediaWiki instance. Notice the unstaged changes in MediaWiki core.
  4. In the browser that's running MediaWiki on http://localhost:8080, navigate to the CodexExample page /wiki/Special:CodexExample page (http://localhost:8080/wiki/Special:CodexExample)
  5. In the CodexExample repo, make changes in this "playground" branch to check for style loading errors in MediaWiki core.

Making changes in CodexExample:

  1. Copy code from a component demo eg. Menu with pending state to App.vue in CodexExample.
    • Import components and composables from Codex using require( '../../codex.js' ).
      • Example:const { CdxMenu, CdxTextInput, useGeneratedId, useFloatingMenu } = require( '../../codex.js' );
    • Import icons from Codex using require( '../icons.json' );.
      • Example: const { cdxIconCamera, cdxIconBook, cdxIconClock } = require( '../icons.json' );
  2. In extension.json (ref), add the icons, components and composables that are required (or imported).
    • Add the component and composables to "codexComponents" list in extension.json
    • Add icons to the "callbackParam" list in extension.json
  3. In extension.json, add the styles to load (after the component loads) to "ext.codexExample.secondThing"
  4. Refresh the Special:CodexExample page after changes are made in CodexExample. You'll mainly be working in files, App.vue and extension.json.
  5. Check that the selector styles are not being overridden.
  6. In the browser console, run mw.loader.load( 'ext.codexExample.secondThing' ) to load the styles of subcomponents and check for any style loading errors

Netlify links to view changes made from this patch

Event Timeline

Restricted Application added a subscriber: Aklapper. · View Herald Transcript

Change 972068 had a related patch set uploaded (by Catrope; author: Eric Gardner):

[design/codex@main] Input with Button mixin: Increase specificity of button styles

Change 980457 had a related patch set uploaded (by LWatson; author: LWatson):

[design/codex@main] styles: Increase css specificity of subcomponents

lwatson changed the task status from Open to In Progress.Dec 10 2023, 12:22 AM
lwatson updated the task description. (Show Details)

Change 972068 abandoned by LWatson:

[design/codex@main] Input with Button mixin: Increase specificity of button styles


This is a proof of concept. See

T353885 affects this. We have yet to choose between two possible ways of addressing that issue, but thankfully the impact on this task is the same for both (changing &__label.cdx-label to &__label, &__label.cdx-label and changing other affected selectors similarly). So we could punt on the rest of T353885 until the new year, and just do the comma selector thing as part of this task for now (maybe with a TODO comment above the affected selectors that points to T353885).

Change 980457 merged by jenkins-bot:

[design/codex@main] styles: Increase CSS specificity of subcomponents

Change 989250 had a related patch set uploaded (by LWatson; author: LWatson):

[mediawiki/core@master] Update Codex from v1.2.0 to v1.2.1

Change 989250 merged by jenkins-bot:

[mediawiki/core@master] Update Codex from v1.2.0 to v1.2.1