Document colour roles in the brand baseline, and resolve the gradient and alpha restrictions it contradicts

Open Beginner friendly
  • Is something wrong?
#376 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 2 days

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
72/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
css, markdown, typescript
Domain
design, documentation

Research direction

Read .agents/skills/brand-baseline/SKILL.md and compare its palette guidance with the role comments and theme tokens in website/src/css/custom.css. Document colour roles and track hues, then resolve the stated gradient and alpha restrictions and record the dark-theme selector rule. Done when the guide matches the shipped styles and clearly states each colour’s role and allowed use.

Written by the indexing model from the issue text.

Description

documentation
Page or section

.agents/skills/brand-baseline/SKILL.md (the file that serves as the design system guide) and website/src/css/custom.css.

Issue description

The palette is documented, the way it is used is not, and two of the guide's own restrictions no longer match what the site ships.

The guide lists swatches by name and hex: Genie Blue #2353FF, Midnight #1D1D1B, Moon #F5F3EB, Vanilla Sunset #FEC104, Blazing Amber #FF4B11, Raspberry Blush #F8908F, Caramel Delight #FCE4C6, Rich Black, plus Shadow, Twilight, Winter Steel and Pure White.

What it does not say is what each colour is for. That knowledge currently exists only as comments in custom.css, and nowhere a person or an agent could find it before touching the stylesheet:

Role Colour Light Dark
Action, links, primary button Genie Blue #2353FF #4D91FF
Text and item rules Midnight #1D1D1B #F5F3EB
Scheduled, as a filled chip with midnight label Vanilla Sunset #FEC104 #FEC104
Careful (warning callouts), contributor hover ring Blazing Amber #C13A0B text, #FF4B11 mark #FF8F6B / #F0764F
Band surfaces White and Moon #FFFFFF / #F5F3EB #1D1D1B / #2C2B2B
Navbar and footer surfaces Genie Blue #2353FF #2353FF

On top of that, five track hues were added during the landing page work and are in no deck at all. Three are the languages' own colours, two are ours:

Track Hue Light Dark Contrast on the tab it sits on
dApp and smart contracts Genie Blue #2353FF #4D91FF 5.6 / 5.47
Infrastructure and DevOps Raspberry, darkened #C2185B #F8908F 5.87 / 7.54
Core protocol, Haskell Haskell purple #5D4E8C #A794DE 7.16 / 6.38
Core protocol, Rust Rust orange #CE422B #F0764F 4.73 / 5.96
Core protocol, Go Go cyan, darkened #0B87AD #45C4E6 4.13 / 8.27

Three points where the guide and the build disagree:

  1. "No gradients." Resolved in 3abd1f3: the footer is solid Shadow #2C2B2B, and the dead .hero gradient rule is deleted. custom.css now contains no linear-gradient at all.
  2. "No transparency or blend modes. Solid fills only." This one is open. custom.css now contains 29 rgba() declarations, after the footer rebuild in 8a5e4b8 removed the rgba(255, 255, 255, 0.8) copyright rule along with the old footer, and Infima's alert components ship an rgba highlight. The warning alert has been given a solid replacement, the other admonitions have not. The track tints use color-mix, which resolves to an opaque colour, so those are compliant in effect.
  3. Semantics are missing entirely. Nothing states that blue means "you can act on this", that midnight is structure, that vanilla is reserved for "scheduled", or that blazing now means "careful" and the footer. Without that, a future change can reuse vanilla for decoration and the chip stops meaning anything.

Not urgent and nothing is broken for a reader. The cost is drift: every colour decision of the last week exists in one stylesheet's comments, and the guide that governs them documents swatches without saying what any of them is for.

Proposed change
  • Add a ## Colour roles section to .agents/skills/brand-baseline/SKILL.md: one row per job, with the light and dark value and the contrast each clears, plus the rule that a colour carries at most three meanings before it becomes decoration.
  • Add the five track hues to the palette section, marked as language-derived except the two that are ours, with the note that they are marks and washes only, never text.
  • Decide the gradient question once: either drop the restriction and document the footer gradient as the sanctioned exception, or flatten the footer to a solid #1A202C and delete the dead .hero gradient rule.
  • Same for alpha: allow it for text at 80% on the dark footer, or convert those to solid values.
  • Note in the guide that dark-theme tokens must be declared on html[data-theme='dark'], because Infima declares its own dark tokens on that selector and a bare [data-theme='dark'] block loses every contested token silently. That bug was live until it was found: the warning callouts stayed Infima mustard while the brand values sat unused.

This is a concrete sub-item of #300, which proposes the token baseline and the brand assets page. The palette exists today; the roles and the conflict resolution are what is missing.

Checks
  • I searched existing issues and discussions
  • This is about documentation (not a feature request or bug)
Dominant language
TypeScript
Stars
13
Forks
24
Avg merge
3d 1h
Merged PRs (30d)
34

Getting set up

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.

More from IntersectMBO/developer-experience

All issues in IntersectMBO/developer-experience

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.