Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

feat: Add support for design tokens #34

Open
wants to merge 5 commits into
base: master
Choose a base branch
from
Open

feat: Add support for design tokens #34

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
03268f5
feat: Add support for design tokens
xitij2000 Nov 9, 2023
9d3e0b2
docs: Add README for design tokens, style dictionary and runtime theming
xitij2000 Jan 6, 2024
98643d9
Update README.md
xitij2000 Jan 16, 2024
4e0b1f9
Update README.md
xitij2000 Jan 16, 2024
b253ebc
fix: fix based on learnings from moe
xitij2000 Mar 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .editorconfig
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
[*.json]
indent_style = space
indent_size = 2
37 changes: 37 additions & 0 deletions .gitlab-ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
stages:
- build
- deploy

build themes:
stage: build
image: node:latest
cache:
- key:
files:
- package.json
- package-lock.json
paths:
- node_modules
before_script:
- npm install
script:
- npm run build
artifacts:
paths:
- dist/
when: on_success

deploy s3:
stage: deploy
needs:
- build themes
image:
name: amazon/aws-cli:latest
entrypoint:
- '/usr/bin/env'
script:
- aws s3 cp dist/ s3://$S3_BUCKET/$THEME_PATH --recursive --acl public-read
rules:
# Only deploy if merging to default branch and if a bucket is defined
- if: '$CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH && $S3_BUCKET'
when: always
1 change: 1 addition & 0 deletions .nvmrc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
v18
112 changes: 110 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

This skeleton theme is used to customize the themes of Open edX instances using the `simple-theme` role from the `edx/configuration` repository.

# List of available SASS variables for customization
## List of available SASS variables for customization

Below is the list of available SASS variables for customization. Check `lms/static/sass/theme-overrides.scss` for the details of what these variables are used for and as the authoritative source for the list of variables.

Expand Down Expand Up @@ -116,7 +116,7 @@ variables, and the file `lms/static/sass/_lms-overrides.scss` that imports these
You can then install and use it as a regular theme. Run `make dev.static.lms` to make
sure that the latest changes are picked up.

# [IN DEVELOPMENT] Use as branding package for MFEs
## Use as branding package for MFEs
This can also be used as a [branding package for MFEs](
https://open-edx-proposals.readthedocs.io/en/latest/oep-0048-brand-customization.html).
To do so install this package as an override to `@edx/brand`. Any variables specified in
Expand All @@ -130,3 +130,111 @@ the following ansible config:
MFE_DEPLOY_NPM_OVERRIDES:
- "@edx/brand@file:/edx/var/edxapp/themes/simple-theme/"
```

## WIP: Usage with style dictionary / design tokens

Design tokens present a new way of customising styles using variables that are
then translated into different forms depending on the platform they are used in.

For instance a token like `color.brand.base` could translate to a SCSS variable
called `$brand-base` a css variable called `--pgn-color-brand-base` or be output
in an XML that can be used for styling Android. For now the focus of Paragon is
on CSS variables.
xitij2000 marked this conversation as resolved.
Show resolved Hide resolved

To customise a theme using this system, you'll need to provide all the variables
that you want to override in JSON files. You can look at the JSON files in the
Paragon repository ([currently in the alpha branch](https://github.com/openedx/paragon/tree/alpha/tokens/src)) to see how they are used and what all can be
customised.

In the `tokens/core` or `tokens/light` directories (light is the theme name, you
can have other names) you can create JSON files that override any of the values
in Paragon. You can see how these JSON files are structured at the link above.
While Paragon follows a strucure above, based on component names, the variable
type etc. This is not necessary, the exact structure doesn't matter, they are
all loaded and merged into one dictionary of styles and the output theme will
output it as CSS variables so they can be loaded by the custom theme.
navinkarkera marked this conversation as resolved.
Show resolved Hide resolved

This is a two-step process:

1. Building the tokens: The `paragon build-tokens` build tokens command compiles
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
1. Building the tokens: The `paragon build-tokens` build tokens command compiles
1. Building the tokens: The `npm build-tokens` build tokens command compiles

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The command being the scenes is paragon. I'm just running it via npm scripts.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@xitij2000 Yes, I know. People will need to use npm as they cannot directly run paragon commands which is why I am suggesting this change.

the JSON style dictionaries into CSS file sin the `paragon/css/` directory.
xitij2000 marked this conversation as resolved.
Show resolved Hide resolved
These are supposed to be committed to the repository.
2. Building the SCSS: The build token CSS files are then compiled into a brand
theme in the dist folder using the `paragon build-scss` command. The contents
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
theme in the dist folder using the `paragon build-scss` command. The contents
theme in the dist folder using the `npm build-scss` command. The contents

of the dist directory are what needs to uploaded to the CDN and will be
loaded by MFEs.

Unlike SCSS variables, which are evaluated at build time and then applied to a
theme, CSS variables are evaluated at run time. This means you can build a base
Paragon theme that is using CSS variables and then you can swap out the
stylesheet that defines all the variables to quickly change the theme at
runtime.

To use the custom theme, you no longer need to install the custom branding
package, instead you provide the theme stylesheet URLs via the MFE config API.
The built themes can be uploaded to a CDN and those URLs can be specified via
the MFE config API in the following format:

```json
{
...
"MFE_CONFIG": {
...
"PARAGON_THEME_URLS": {
"core": {
"urls": {
"default": "https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/core.min.css",
"brandOverride": "https://cdn.jsdelivr.net/npm/@edx/brand-edx.org@#brandVersion/dist/core.min.css"
}
},
"defaults": {
"light": "light"
},
"variants": {
"light": {
"urls": {
"default": "https://cdn.jsdelivr.net/npm/@edx/paragon@$paragonVersion/dist/light.min.css",
"brandOverride": "https://cdn.jsdelivr.net/npm/@edx/brand-edx.org@$brandVersion/dist/light.min.css"
}
}
}
}
}
}

```

The above are the vanilla Paragon stylesheets. The core stylesheets contain the
bulk of the Paragon styling while the variants have the style variables that
modify how the core theme applies. For both of those you have a `default` and a
`brandOverride`. The default is the core theme whereas the `brandOverride` applies
on top. This keeps the theme smaller since you don't need to include and update
all the variables from the core theme.

In the above example when configuring the theme for an instance, you would
upload the `dist` folder contents to a CDN, and add the path to `core.min.css`
and `light.min.css` to the appropriate places. You can also create other themes
like a `dark` theme or a separate theme for each site.

NOTE: CSS variables are technically called CSS custom properties but they are
called variables here because that more closely corresponds with how they are
being used here.

## WIP: Automatically deploying a runtime theme to S3 via gitlab CI

This repo has a GitLab CI configuration to automatically deploy to AWS S3 if
configured.

To use that you need to configure the environment variables that AWS CLI needs
for S3. At minimum you need:

- AWS_ACCESS_KEY_ID
- AWS_SECRET_ACCESS_KEY
- S3_BUCKET

If deploying to DigitalOcean buckets or some other S3-compatible storage you can
specify `AWS_ENDPOINT_URL` as well.

If the files need to be deployed to a sub-path, set `THEME_PATH` as well. This
can be used to build and deploy themes to a CDN after changing design tokens to
update or fix a theme.
38 changes: 19 additions & 19 deletions common/_overrides.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,35 +32,35 @@ a:not(.btn):hover,
a:not(.btn):focus,
a:visited:not(.btn):hover,
a:visited:not(.btn):focus {
color: $link-color;
color: var(--pgn-color-link-base);
}

.btn-primary,
.btn-brand {
// Set the styles for the primary button
@include btn-styles(
$btn-primary-bg,
$btn-primary-color,
$btn-primary-font-size,
$btn-primary-font-weight,
$btn-primary-border-color,
$btn-primary-border-width,
$btn-primary-hover-bg,
$btn-primary-hover-color,
$btn-primary-hover-border-color
var(--pgn-color-btn-bg-primary),
var(--pgn-color-btn-text-primary),
var(--pgn-typography-btn-font-size-primary),
var(--pgn-typography-btn-font-weight-primary),
var(--pgn-color-btn-border-primary),
var(--pgn-size-border-width-primary),
var(--pgn-color-btn-hover-bg-primary),
var(--pgn-color-btn-hover-text-primary),
var(--pgn-color-btn-hover-border-primary)
);
}

.btn-outline-primary {
@include btn-styles(
$btn-secondary-bg,
$btn-secondary-color,
$btn-secondary-font-size,
$btn-secondary-font-weight,
$btn-secondary-border-color,
$btn-secondary-border-width,
$btn-secondary-hover-bg,
$btn-secondary-hover-color,
$btn-secondary-hover-border-color
var(--pgn-color-btn-bg-secondary),
var(--pgn-color-btn-text-secondary),
var(--pgn-typography-btn-font-size-secondary),
var(--pgn-typography-btn-font-weight-secondary),
var(--pgn-color-btn-border-secondary),
var(--pgn-size-border-width-secondary),
var(--pgn-color-btn-hover-bg-secondary),
var(--pgn-color-btn-hover-text-secondary),
var(--pgn-color-btn-hover-border-secondary)
);
}
68 changes: 34 additions & 34 deletions common/_variables.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,41 +1,41 @@
// Set default colors in case they aren't set on the parent file
$main-color: #ff8000 !default;
$link-color: #126f9a !default;
$header-bg: #fff !default;
$footer-bg: #fff !default;
$main-color: var(--pgn-color-main) !default;
$link-color: var(--pgn-color-link-base) !default;
$header-bg: var(--pgn-color-header-bg) !default;
$footer-bg: var(--pgn-color-footer-bg) !default;

$btn-font-size: null !default;
$btn-font-weight: null !default;
$btn-border-width: 1px !default;
$btn-font-size: var(--pgn-typography-btn-font-size-base) !default;
$btn-font-weight: var(--pgn-typography-btn-font-weight) !default;
$btn-border-width: var(--pgn-size-btn-border-width) !default;

$btn-primary-bg: theme-color("primary") !default;
$btn-primary-color: theme-color("inverse") !default;
$btn-primary-font-size: $btn-font-size !default;
$btn-primary-font-weight: $btn-font-weight !default;
$btn-primary-border-color: theme-color("primary") !default;
$btn-primary-border-width: $btn-border-width !default;
$btn-primary-hover-bg: theme-color("primary") !default;
$btn-primary-hover-color: theme-color("inverse") !default;
$btn-primary-hover-border-color: theme-color("primary") !default;
$btn-primary-bg: var(--pgn-color-btn-bg-primary) !default;
$btn-primary-color: var(--pgn-color-btn-text-primary) !default;
$btn-primary-font-size: var(--pgn-typography-btn-font-size-primary) !default;
$btn-primary-font-weight: var(--pgn-typography-btn-font-weight-primary) !default;
$btn-primary-border-color: var(--pgn-color-btn-border-primary) !default;
$btn-primary-border-width: var(--pgn-size-btn-border-width-primary) !default;
$btn-primary-hover-bg: var(--pgn-color-btn-hover-bg-primary) !default;
$btn-primary-hover-color: var(--pgn-color-btn-hover-text-primary) !default;
$btn-primary-hover-border-color: var(--pgn-color-btn-hover-border-primary) !default;

$btn-secondary-bg: theme-color("primary") !default;
$btn-secondary-color: theme-color("inverse") !default;
$btn-secondary-font-size: $btn-font-size !default;
$btn-secondary-font-weight: $btn-font-weight !default;
$btn-secondary-border-color: theme-color("primary") !default;
$btn-secondary-border-width: $btn-border-width !default;
$btn-secondary-hover-bg: theme-color("primary") !default;
$btn-secondary-hover-color: theme-color("inverse") !default;
$btn-secondary-hover-border-color: theme-color("primary") !default;
$btn-secondary-bg: var(--pgn-color-btn-bg-secondary) !default;
$btn-secondary-color: var(--pgn-color-btn-text-secondary) !default;
$btn-secondary-font-size: var(--pgn-typography-btn-font-size-secondary) !default;
$btn-secondary-font-weight: var(--pgn-typography-btn-font-weight-secondary) !default;
$btn-secondary-border-color: var(--pgn-color-btn-border-secondary) !default;
$btn-secondary-border-width: var(--pgn-size-btn-border-width-secondary) !default;
$btn-secondary-hover-bg: var(--pgn-color-btn-hover-bg-secondary) !default;
$btn-secondary-hover-color: var(--pgn-color-btn-hover-text-secondary) !default;
$btn-secondary-hover-border-color: var(--pgn-color-btn-hover-border-secondary) !default;

$btn-sign-in-font-size: $btn-font-size !default;
$btn-sign-in-font-weight: $btn-font-weight !default;
$btn-sign-in-border-width: $btn-border-width !default;
$btn-sign-in-font-size: var(--pgn-typography-sign-in-btn-font-size) !default;
$btn-sign-in-font-weight: var(--pgn-typography-sign-in-btn-font-weight) !default;
$btn-sign-in-border-width: var(--pgn-size-sign-in-btn-border-width) !default;

$btn-register-font-size: $btn-font-size !default;
$btn-register-font-weight: $btn-font-weight !default;
$btn-register-border-width: $btn-border-width !default;
$btn-register-font-size: var(--pgn-typography-register-btn-font-size) !default;
$btn-register-font-weight: var(--pgn-typography-register-btn-font-weight) !default;
$btn-register-border-width: var(--pgn-size-register-btn-border-width) !default;

$btn-logistration-font-size: $btn-font-size !default;
$btn-logistration-font-weight: $btn-font-weight !default;
$btn-logistration-border-width: $btn-border-width !default;
$btn-logistration-font-size: var(--pgn-typography-logistration-btn-font-size) !default;
$btn-logistration-font-weight: var(--pgn-typography-logistration-btn-font-weight) !default;
$btn-logistration-border-width: var(--pgn-size-logistration-btn-border-width) !default;
Loading