Write application tokens ADR
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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