openedx / openedx/paragon

Write application tokens ADR

Open
#4,292 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
140
Forks
100
Avg merge
1h 3m
Merged PRs (30d)
30

Description

We should cover naming and lifecycle like https://github.com/openedx/frontend-plugin-framework/blob/master/docs/decisions/0003-slot-naming-and-life-cycle.rst does

We should also make it clear what application tokens are part of the API contract. https://github.com/openedx/frontend-app-authoring/pull/2837/ added a bunch of CSS vars purely from a DRY/avoiding hardcoded color hex values perspective. Brand packages can modify those now, but that doesn't mean we want to commit to supporting those CSS vars. We shouldn't prevent application developers from using CSS vars for cleaner style architecture out of fear that theme authors will rely on those and they'll become part of an API contract we need to support.

Another little thing to decide is how to handle fallbacks in var( vs having application stylesheets define values for vars on :root. In frontend-app-catalog we use the fallback method for the banner background color, and there's no downside there because it's consumed in one place. In the authoring PR example using fallbacks would defeat the purpose of using CSS vars to keep it DRY. I'm ok with having this be a judgement call thing, but if we want to standardize that's worth considering too.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading the linked slot-naming and life-cycle ADR, then compare the fallback usage in frontend-app-catalog with the CSS variables added in frontend-app-authoring PR #2837. The ADR should document application-token naming and lifecycle, distinguish API-contract tokens from internal CSS variables, and explain how fallback decisions are handled.

Written by the indexing model from the issue text.

Assessment

Tech stack
css
Domain
design, documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.