From f29e66ca354b2deb36ef6ccf4bacc5d71a8bfd5a Mon Sep 17 00:00:00 2001 From: Adam Stankiewicz Date: Wed, 19 Jul 2023 10:04:43 -0400 Subject: [PATCH] docs: design tokens ADR (#1929) --- ...support.md => 0018-typescript-support.rst} | 4 +- ...0019-scaling-styles-with-design-tokens.rst | 261 ++++++++++++++++++ .../assets/style-dictionary-build-diagram.png | Bin 0 -> 196232 bytes 3 files changed, 263 insertions(+), 2 deletions(-) rename docs/decisions/{0018-typescript-support.md => 0018-typescript-support.rst} (94%) create mode 100644 docs/decisions/0019-scaling-styles-with-design-tokens.rst create mode 100644 docs/decisions/assets/style-dictionary-build-diagram.png diff --git a/docs/decisions/0018-typescript-support.md b/docs/decisions/0018-typescript-support.rst similarity index 94% rename from docs/decisions/0018-typescript-support.md rename to docs/decisions/0018-typescript-support.rst index 601018845d..be67169448 100644 --- a/docs/decisions/0018-typescript-support.md +++ b/docs/decisions/0018-typescript-support.rst @@ -1,5 +1,5 @@ -18. TypeScript support. ----------------------------------------------------------------- +18. TypeScript support +----------------------- Status ------ diff --git a/docs/decisions/0019-scaling-styles-with-design-tokens.rst b/docs/decisions/0019-scaling-styles-with-design-tokens.rst new file mode 100644 index 0000000000..3247d160e0 --- /dev/null +++ b/docs/decisions/0019-scaling-styles-with-design-tokens.rst @@ -0,0 +1,261 @@ +19. Scaling the Paragon design system's styles with design tokens and ``style-dictionary`` +########################################################################################### + +Status +====== + +Provisional + +Context +======= + +A critical component of the Open edX platform is the ability to customize its visual styles to reflect the custom brand of its consumers in the Open edX community. Historically, the Open edX platform (via ``edx-platform``) has supported a comprehensive theming system fulfilling the community's theming needs, including brand customization but also functionality, too (e.g., modifying, adding, or removing user interface elements). However, as we've moved towards React micro-frontends, the theming from a brand customization perspective has been largely replaced by the theming system provided by the Paragon design system. + +Within Paragon, "theming" predominantly refers to brand customization as it relates to visual styles. It does not intend to be responsible for customization of functionality as in the historical sense of comprehensive theming in ``edx-platform``. The Frontend Working Group's roadmap includes improvements to micro-frontend customizability. + +Current styles architecture +--------------------------- + +Today, Paragon's core styles are heavily based on `Bootstrap 4 `__. The decision to rely on Bootstrap was to extend a popular, existing responsive CSS framework to get an initial design system created more efficiently than creating all styles from scratch in addition to general knowledge and awareness of Bootstrap throughout the frontend community (see `OEP-16 `__ for more details). + +Bootstrap 4 supports theming of visual styles through SCSS variables. As a result, Paragon's current theming system also relies overriding SCSS variables, both from core Bootstrap and custom Paragon variables. + +While Paragon's SCSS theming system has largely supported Open edX's transition from building legagy UIs in Django to React micro-frontends, we have identified several challenges that hinder its continued scalability and use in micro-frontends throughout Open edX. + +Challenges with current styles architecture +------------------------------------------- + +* **On theme changes, all its consuming applications must be upgraded, re-built, and re-deployed.** + + * Because Paragon currently heavily relies on SCSS variables for its theme, when any SCSS variable(s) are changed, every application consuming that theme needs to upgrade to the new version, be re-built, and get re-deployed. + + * With applications needing to be rebuild/redeployed, it's a significant effort to upgrade all applications to the new theme, especially if trying to do all applications at once. + + * With runtime theming via CSS variables, when a change is made to the theme, only the theme itself should need to get re-built, and the styles should automatically get applied to all consuming applications without needing to explicitly upgrade, re-build, and re-deploy those applications. + +* **Paragon styles are not platform agnostic nor a single source-of-truth.** + + * The styles associated with Paragon themes are largely only accessible in environments that support SCSS as pretty much all Paragon's style properties are baked into SCSS variables. + * Ideally, the style properties would be defined in a platform agnostic way such that they can be transformed for various platforms, like iOS and Android apps or even a Figma integration. + + * *Note: these additional platform support ideas is more of a longer-term vision for how we could extend the design tokens work further in the future.* + +* **Supporting both system-wide themes and organizational themes.** + + * The primary theming use case for Paragon is largely around system-wide theming, where all applications in the Open edX ecosystem share the same theme. + * However, there are use cases for organizational themes, too (i.e., updating the colors for specific partners/organizations, enterprise customers, etc.). + + * This is not well supported today and largely requires overriding CSS classes from Paragon rather than the desired approach of overriding underlying CSS variable(s). This an anti-pattern as Paragon class names should really be considered internal implementation details of Paragon components, and not used by consumers directly. For example, the Enterprise MFEs within Open edX (e.g., frontend-app-learner-portal-enterprise) inject ``