Hello everyone.
For the past week, I’ve been working on @edly-io/brand-openedx for Paragon 23, and I’ve hit a few friction points I’ve ranted about in the #general Slack channel.
I’ve been told to share them in a more appropriate place, so I’m writing them down here, in no particular order:
Error Messages
If you create a theme by any name other than light, and define a colour design token called primary:
{
"$type": "color",
"color": {
"primary": {
"base": {
"$value": "#15376D"
}
}
}
}
the following error occurs on npm run build-tokens:
css
✔︎ ./paragon/build/core/variables.css
✔︎ ./paragon/build/core/custom-media-breakpoints.css
An error occurred: TypeError: Cannot read properties of undefined (reading 'default')
The error message is meaningless, there’s no stack trace, no file name, no line number, no key path. (Here, it’s easy to see the culprit is the primary colour, but with a real-world color.json file, I had to bisect the JSON, which is an ordeal because it doesn’t support comments. JSON should never be used as a configuration format.)
The exact same file in a folder called light instead of dark is processed without error, because it inherits Paragon’s light theme tokens.
You’d think it’s looking for a default value for color.primary.base, because you’ve seen it defined in some design token files, but no. It’s looking for color.primary.base.actions.default (notice how it doesn’t complain about the missing actions object, only its default key.) It has to be defined like this:
{
"$type": "color",
"color": {
"primary": {
"base": {
"$value": "#15376D",
"actions": {
"default": "{color.action.default.primary.base}"
}
}
},
"action": {
"default": {
"primary": {
"base": {
"modify": [
{
"type": "darken",
"amount": "0.1"
}
],
"$value": "{color.primary.base}"
}
}
}
}
}
}
I don’t understand this at all. If it’s not inheriting from the light theme, why is it looking for an actions object? And if it is, why is it not finding it? A colour named differently is perfectly happy without any of this.
But the bigger problem is not this missing actions object, it’s the uselessness of the error message. It’s just impossible to guess where the problem lies when such an error occurs, and the --verbose flag is no help.
Interrupting the Build
The build-scss command cannot be interrupted. It doesn’t respond to signals. When it takes two minutes and up to build with the core, it’s a problem. Adding process.on( SIG(TERM|INT), ... ) in the code does not help, it’s the sass compilation that hogs the shell.
Missing Folder
build-scss does not create its destination folder, dist/. If you invoke the command after removing the folder, it will display an error, but will still tread on for two minutes compiling the SCSS, before failing and discarding it. And if you’re fortunate to see the error, remember, you can’t interrupt the process anyway.
Wrong and meaningless argument help text
Some help text is wrong. Other is just not helpful.
Here the help text for --source is the one for --replacementType:
replace-variables
-s, --source Default: ''
Type of replacement: usage or definition. If set to "definition" the command will only update SCSS variables definitions with CSS variables, if set to "usage" - all occurrences of SCSS variables will we replaced
-t, --replacementType [usage|definition], Default: definition
Type of replacement: usage or definition. If set to "definition" the command will only update SCSS variables definitions with CSS variables, if set to "usage" - all occurrences of SCSS variables will we replaced
This does not mean anything:
build-tokens
--source-tokens-only Default: false
Include only source design tokens in the build.
This gives no indication about what it actually does, or why I would desire this, or not:
build-scss
--defaultThemeVariants Default: light
Specifies default theme variants. Defaults to a single 'light' theme variant.
You can provide multiple default theme variants by passing multiple values, for
example: `--defaultThemeVariants light dark`
Moreover, commands will happily accept and ignore flags it doesn’t know about, making typos difficult to detect.
Should I open issues on the repo? I don’t think I can do PRs, except maybe for the --source option of replace-variables, because I don’t do node development.