Just wanted to share that I decided to try Codex for a community webservice: https://hitaden.toolforge.org/
Still have some difficulties with the tokens sytem, but otherwise, it is a nice framework.
(Currently the backend is broken; also had to learn how to deploy on Toolforge with Build Service).
Great to hear! Feel free to reach out if you need help with anything. Most current uses of Codex are within MediaWiki, so we're eager to hear from people who are using it outside of MW, especially if you can point us to things that aren't well documented for that use case.
Sure. Should I share here or on Phabricator?
One recent case is the following. With showSearchProgressBar = false, this code snippet works:
<div v-show="showSearchProgressBar"><cdx-progress-bar
inline
aria--label="ProgressBar example"
v-show="showSearchProgressBar"
/>
</div>
and got translated in:
<div style="display: none;"><!-- ARIA progressbar default values are `aria-valuemin="0"` and `aria-valuemax="100"`,
hence omitting them here. -->
<div
class="cdx-progress-bar cdx-progress-bar--inline cdx-progress-bar--enabled"
role="progressbar"
aria-hidden="true"
aria-disabled="false"
>
<div class="cdx-progress-bar__bar"></div>
</div>
</div>
This one doesn't:
<cdx-progress-bar
inline
aria--label="ProgressBar example"
v-show="showSearchProgressBar"
/>
and got translated in:
<!-- ARIA progressbar default values are `aria-valuemin="0"` and `aria-valuemax="100"`, hence omitting them here. -->
<div
class="cdx-progress-bar cdx-progress-bar--inline cdx-progress-bar--enabled"
role="progressbar"
aria-hidden="true"
aria-disabled="false"
>
<div class="cdx-progress-bar__bar"></div>
</div>
I think it is because the cdx-progress-bar component is getting wrapped? I don't have the knowledge to share hypothesis. I don't know if it is linked to my framework (Astro) doing some static site generation. Do you experience the same on your side?
Hmmm I think this might be because the component outputs a comment at the start, and Vue tried to apply the v-show to the comment, which doesn't work. I already noticed that we were generating comments when we shouldn't (those should be for development only), and I already planned to look into it in the new year. I'm about to go on vacation for the holidays but I'll make this the first thing I look into when I come back in early January.
In the meantime, could you file a bug report in Phabricator and link it here? That will make it easier for us to track.
Oh no, already two weeks. A bit forgot about it. Thanks for filling. I'm gonna break the CSS-only components now! I was just using Vue to test it all. 🫡
Apologies for the late follow-up, I was sick last week. This bug should be fixed in the latest release of Codex (1.2.1), which was released on January 9th.
What an idea to be sick... 😁 Thanks for the notice!
I'd like to ask you another and rather bold question: does the team think that the Codex "design tokens" are stable enough to be incorporated by volunteers into the Wikimedia projects themselves? For example, the colors could be used to update models that have unsightly colored backgrounds.
I've also looked at the MediaWiki Skin Variables Architecture graphic, but I need your knowledge to know the ins and outs of using tokens. If the nomenclatures are unified, are we safe to use rules defined in mediawiki.skin.defaults.less? Are all the rules always delivered by MediaWiki? No problems linked to potential tree shaking with Vue or minified CSS?
Thanks!
Eh, it seems related to phab:T346469. And the answer is no. And also, it seems I clearly mis-under-understand the architecture.
Unfortunately the design tokens are only available in MW as Less variables at the moment, so they can only be used in Less styles. On-wiki styles (Gadgets, user styles, TemplateStyles) can only use CSS, not Less. I looked into fixing that, but unfortunately the lack of Less support was a deliberate decision. So instead, we need to find a way to provide the design tokens in CSS. I filed this task for that a few months ago, as part of a larger effort to support Codex in Gadgets / user scripts, which we plan to work on in the coming months.
So in summary, tokens are not currently available in on-wiki styles due to technical barriers, and we plan to fix that some time in the next few months. Once that is fixed, I completely agree that using the tokens for on-wiki templates/modules would be a great idea. In addition to making the color scheme more consistent, using tokens would probably also help make those things compatible with the upcoming dark mode feature. (Some of the technical architecture decisions around dark mode are still unsettled and I'm not in charge of them, so I can't make any promises. But I think that "encourage on-wiki content to use CSS variables that correspond to (a subset of) Codex tokens" or something similar to that is likely to be part of the plan.)
Alright, since I had my answers, I ditched my prototype and the today-published new version is using Codex with Nuxt. And it works great. Thanks for your work!
Perhaps I'm just being silly, but it does not seem possible to easily align the text of a toggle to the right of the toggle? Wherever in the code I put the label, it always seems to go to the left of the toggle, and not to the right. This presents issues when the labels are not all the same size in length, as if they are stacked vertically, the toggle is in different places on each line, which is visually unappealing.
Is there a way to do this and it just isn't documented? Or is there no way? I'd rather not align all of the toggles to the right of the screen. This is using the CSS only toggles in MediaWiki itself.
Since accessibility is so critical, it's nice to read that it's "built-in" but are there some more details? I'm interested in how the new Codex will enable MediaWiki and other projects to be fully compliant with WACG and also how developers or testers should use tools to verify accessibility in Codex.
Answering my own question, I see the README states "Web accessibility compliant (Web Content Accessibility Guidelines 2.1 level AA)"
Digging further, there is info in the project sources (docs) at packages/codex-docs/docs/style-guide/accessibility.md which includes reference to wikipedia:Wikipedia:Manual_of_Style/Accessibility Wikipedia's Manual of Style (that goes into great depth about Content Accessibility); plus links to the Accessibility guide for developers that describes techniques, guidelines and some tools for developers.
It's only a suggestion since I'm not that familiar with the sources, the tools (such as automated cross-browser testing), and project contributors' methods but perhaps there should be some guideline or specific process added to e.g. https://doc.wikimedia.org/codex/latest/contributing/contributing-code/testing-components.html that says something like "Open WAVE or your Firefox Accessibility Inspector to confirm WCAG 2.1 level AA compliance".
When I try the button example in a new and plain Vue project(npm create vue@latest), the component renders and its functionally works but it got no styles. I could import the full CSS as the Codex Starter Template on Gitlab does it but given the documentation and that such an approach results in tons of unused styles being included there must be a better way?
Unfortunately you have to import the CSS separately. This is not currently well-documented on the Codex documentation site, but we're adding documentation for this in the next release. For now, you can preview the documentation we will be adding here.
@Volker E. (WMF), a translator asked me if we could clarify. Is the code for v0.20.0 faltered or altered? Do we see a typo here? It reads:
Thanks for pointing this out! I have edited this wording slightly.
Wonderful! Allow me to ping the person at translation, and @Tmv: would be updated. Cheers,
OOUI has a nice demo at https://doc.wikimedia.org/oojs-ui/master/demos/?page=widgets&theme=wikimediaui&direction=ltr&platform=desktop. Got a demo for Codex yet? If so, maybe link it in the article. Trying to get an idea of whether or not Codex is visually different from OOUI. Thanks.
The documentation linked to in the first paragraph also contains examples (work in progress, but plenty to have a look at).
Really great documentation so far! As a reader, I was curious what "index.js" should contain, any hints would be appreciated. Perhaps something like Vue.mwCreateApp( { render: ... } ).mount( domElement )?
Yes, that's exactly right, init.js should contain code mounting the component. I've tried to make this clearer by linking to the Vue.js documentation page at the top of the Codex page, and also linking to the section about init files below the example that uses an init file.
One thing that I'd still like to find a place to add is an example showing how all these pieces come together into an example module. That would probably fit best on the Vue.js page.
