## Background## What is it?
- **Description:** Create a CSS/LESS only implementation of Codex components (probably just a subset of them)CSS-only components would be a group of Codex components that are implemented solely by creating standard, shared styles in CSS (or Less), meaning JavaScript would not be required to use them. For example, to use a CSS-only Message component, a developer would either write or generate the markup for the message, then apply the shared styles to their markup, resulting in a no-JS message that has visual consistency with the Vue version of the Message component.
Currently, nearly all Codex components are implemented as Vue.js components, meaning they require JavaScript running on the client to work. Eventually, we hope to have a solution for rendering Vue components on the server (server-side rendering, or SSR), but this will take time, and there still may be use cases for no-JS versions of Codex components even if we have full SSR.
## Impact
### End-user impact
- {icon plus color=green} Users without JavaScript can see and use UIs that have a consistent design that matches our canonical design system, across wikis
- **History:** This is an approach that has been followed by many other design systems; it will help Codex to cover use-cases where using Vue (or JS at all) would not be appropriate{icon plus color=green} Users with slow connections can see and start to use visually consistent UI components while they await the fully interactive JS version of the UI to load
- **Known use case(s):**{icon plus color=green} All users benefit from simple UIs that can be rendered on the server, which load quickly and provide a consistent experience
- Main use case: Allow teams who have performance or security constraints to achieve visual consistency with the design system without using JS/Vue- {icon plus color=green} Non-WMF wikis have a way to provide consistent server-rendered UIs without having to set up SSR
- Secondary use case: Enable rapid prototyping- {icon minus color=red} Potential for double-loading of styles when CSS components are used alongside Codex Codex components (which contain their own styles), or loading styles that aren't needed on the page, either of which could impact performance
- Secondary use case: Create a pathway for building Codex-compliant features that doesn't require JS or Vue knowledge- {icon minus color=red} [For class implementation] Providing styles for specific CSS classes could result in these classes being misused on-wiki, e.g. applying interface styles to content, which could cause visual inconsistencies (this was seen with mediawiki.ui)
- **Considerations:** Can we avoid duplication by having the CSS "components" share styles with the Vue components? Would it make sense to publish a `codex-styles` package that contains LESS mixin, which then gets used in the Codex Vue components?{icon minus color=red} [For class implementation] Potential for breaking visual changes becoming disruptive and difficult to manage if people are just applying CSS classes all over the place.
### User storiesEngineering impact
- As a developer of a feature that cannot use JS for performance or security reasons,{icon plus color=green} While they await an SSR solution, or in situations where SSR cannot be used, engineers can use CSS-only Codex components to style server-rendered elements, enabling them to use the current design system and reducing the need for custom code.
- {icon plus color=green} Engineers with no JavaScript or Vue experience can build UIs with Codex components
- {icon plus color=green} Engineers can use CSS-only components for rapid prototyping with Codex styles, leading to a more consistent UI when the production version is built and enhancing collaboration between engineering and design
- {icon plus color=green} We can eventually deprecate old, inconsistent parts of our systems in favor of a single, centralized set of styles, leading to lower maintenance costs, less confusion, and easier onboarding of new developers
- {icon plus color=green} Abstracting styles out of Vue components will mean having a set of implementation-agnostic base styles that could be applied to a new implementation in the future (e.g. React or a new framework)
- {icon minus color=red} Development costs: building this set of components will require time from DST and other teams to develop and test
- {icon minus color=red} Maintenance costs: DST has to maintain this set of components (n.b. I'd like my UI to have visual consistencythis is better than the status quo of legacy systems with the wider design system.no clear owner, I'd also like to be able to simply re-use pre-defined styles that look and behave correctly instead of having to write them myself.but is still worth noting)
- {icon minus color=red} [For mixin implementation] Developers may find it more time-consuming to apply mixins to their custom classes than to simply use a component class in their markup
### PreviousDesign implementationsact
- **OOUI:** The [[ https://doc.wikimedia.org/oojs-ui/master/demos/demos.php | OOUI PHP ]] work is relevant here{icon plus color=green} Since styles are shared between CSS-only and Vue components in Codex, designers will have less to review when adding or changing components
- **mediawiki.ui** is of concern.- {icon plus color=green} Once we deprecate old systems, designers will have fewer things to keep track of and work on, Former andleading to greater velocity on the current modulessystem
- anchor `a`- {icon plus color=green} Designers who know HTML and CSS can use CSS-only components for rapid prototyping or to make code changes for production UIs
### Other impact
- For Codex: DST would need to move existing Codex component styles out of the Vue component files and into a new shared location.
- `form`- Caching: there may be cases where CSS and JS components become visually out of sync due to different caching behavior of HTML/CSS and JS. DST would likely need to prevent this potential issue.
## What does it block?
- Some WMF teams may be able to start using Codex (and, therefore, the current and canonical design system) if they have access to these components while they're waiting on SSR
## Phases of work and owners
- **Phase 1: Strategy**
- `label`- Owner: DST
- `button`To do:
- Choose an implementation path
- Decide on an MVP implementation and set of components
- Determine development and testing strategy
- **Phase 2: MVP implementation**
- `input[type="text"]`- Owner: DST
- `input[type="search"]`To do:
- Build MVP set of components
- Test them internally and with others outside DST
- **Phase 3: Further implementation**
- `input[type="radio"]`- Owner: DST
- `input[type="checkbox"]`To do:
- Fix potential MediaWiki-specific problems:
- Potential inconsistencies due to caching differences between CSS and JS code
- Figure out how to avoid bloated CSS via double-loading of styles (if this wasn't resolved in Phase 1 and requires, e.g. a ResourceLoader change)
- Enable developers to load a bundle of components or individual components
- Document the components and their usage. This will require figuring out how to represent CSS-only components on the Codex docs site.
- **Phase 4: Application of CSS-only components**
- `select` (limited)- Owner: DST + Web + Others?
- iconTo do:
- Come up with a plan for eventually removing legacy libraries like mediawiki.ui
- Be available to support teams and volunteers implementing CSS-only components in their features
## Cross-team dependencies
- **Web**: The Web team will be a major consumer of these components and should be heavily involved in strategy and testing at least.
- **Performance**: We may need to get the Performance team's blessing on any changes that may impact performance.
### Considerations## Existing Artifacts
Other frameworks typically distribute CSS styles with pre-defined classes (Bootstrap's `.btn`,## Open Questions
1. Do the short and long term benefits outweigh the development costs and justify the changes needed to implement this? `.btn-primary`,Will these components be actively used once we have SSR in place?
2. etc).Which components should we focus on initially? This approach offers good ease-of-use,Long term?
3. but createsWill some coupling between the markup and the framework styles.one actually migrate legacy systems? An alternative approach would be to distribute Codex styles as pure LESS mixins,Who?
4. where the consumer decides where the styles should ultimatelyHow will we implement CSS-only components—via CSS classes that can be applied. to any markup, This approach is described more in [[ https://doc.wikimedia.org/codex/main/using-codex/adrs/04-adr-less-mixins.html | Codex ADR 04 ]].or via Less mixins that must be applied to selectors?
5. How will we mitigate performance impact?