Document how to use your own brand palette - #413
Merged
Merged
Conversation
An app can already supply its own brand palette without any library change, but nothing said so, and the override needs two differently named ramps to be complete: - --color-brand-100..1000 feeds the semantic brand tokens, and through them the PrimeVue preset — primary buttons, checkboxes, focus and selected states, links, and the bg-brand-* / text-brand-* utilities. One set of values covers both colour schemes. - --color-default-bcc-100..1000 feeds the ctx-brand-* context utilities. It is mode-aware, so dark mode takes the same palette in reverse. Overriding only the first leaves ctx-brand-* on the BCC teal while everything else changes, which is easy to hit and hard to diagnose. Documented in the README, and in Foundations > Colors where someone looking for how to change colours will actually go. The llms.txt and llms-full.txt outputs are generated from the Storybook docs pages, so both sections flow into them with no change to the generator. The asterisks in token patterns are written as * in the MDX because MDX parses a pair of them as emphasis, which breaks indexing of the page. A backslash escape parses but leaks the backslash into the generated markdown, since escapes are not processed inside code spans; the numeric entity is decoded on both paths. Verified in Chromium that the documented snippet works verbatim on all three consumer paths — src/style.css, the published theme.css compiled by the app's own Tailwind, and the pre-built style.css with the override in a later stylesheet — in both light and dark mode. Storybook builds, the llms generator's quality check passes, both sections appear in llms-full.txt with the token patterns and links rendered cleanly, and all fourteen docs pages the e2e suite covers load without page errors. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LyYwdsJiGLEyRrJ6tVdnpK
Contributor
There was a problem hiding this comment.
Copilot review overview
🔵 Needs a closer look
Correct the unresolved palette mappings, dark-mode guidance, and stylesheet import instructions.
Review effort: Lite
Findings: None
What changed in this PR
Documents custom brand palette overrides for the component library.
Changes:
- Added complete customization guidance to
README.md. - Added condensed palette documentation to
Colors.mdx. - Documented dark mode, contrast, and CSS placement.
| File | Description |
|---|---|
component-library/README.md |
Brand palette customization instructions and example. |
component-library/docs/foundations/Colors.mdx |
Condensed brand palette guidance and example. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
akselkvitberg
changed the title
akselkvitberg
marked this pull request as draft
September 22, 2026 08:20
The two documented ramps are not enough. The PrimeVue theme preset in
@bcc-code/design-tokens carries the brand ramp as literal values in
primitive.color.brand, and semantic.primary references it through PrimeVue's own
token syntax, resolved at theme-generation time. That chain never sees
--color-brand-*, so --p-primary-color stays on the BCC teal however the
documented ramps are set.
The split is not obvious from the outside: 16 component sections in the preset
read var(--color-*) and do follow the override — button, checkbox, radiobutton,
toggleswitch, select, listbox, multiselect, autocomplete, tag, datepicker, tabs,
stepper, badge, paginator, carousel, progressbar. Ten read {primary.*} and stay
teal — slider, rating, knob, datatable, treetable, tree, editor, timeline,
galleria, fileupload — as do --p-highlight-background and --p-highlight-color,
which colour selection in overlays.
Documents aliasing --p-color-brand-100..1000 to --color-brand-*. That is the
variable --p-primary-* actually resolves through, so the steps map one to one
and both colour schemes follow from the same ten lines, unlike restating
--p-primary-50..950 where the scales differ and dark mode picks a different step.
Recorded as a stopgap. The durable fix belongs in the preset: point
primitive.color.brand at the CSS variables instead of baking in values, and the
third ramp becomes redundant.
Verified in Chromium against rendered components, with the README snippet taken
verbatim: light gives #1d4ed8 on both a primary button and a slider range, dark
gives #bfdbfe, and without the override both stay teal.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LyYwdsJiGLEyRrJ6tVdnpK
Member
Author
|
AI suggest to fix the third ramp in the Token repo. I leave that decision to you.
|
akselkvitberg
marked this pull request as ready for review
September 22, 2026 08:43
Collaborator
|
Can this also be documented in the LLM files, so an AI would easily find it? |
Member
Author
|
LLMs are covered - they are generated from the storybook files. |
jasverix
requested changes
Sep 22, 2026
jasverix
left a comment
jasverix
left a comment
Collaborator
There was a problem hiding this comment.
I've updated tokens in this branch.
Now, --p-color-brand-100 resolves to var(--color-brand-100).
Update documentation accordingly, and then we'll merge.
…5.2.10 design-tokens 5.2.10 points primitive.color.brand at the CSS variables, so --p-primary-* now follows --color-brand-* on its own. The --p-color-brand-* workaround and its explanation are no longer needed, and the docs go back to two ramps. Verified against rendered components on 5.2.10 with the two-ramp README snippet: a primary button and a slider range both give #1d4ed8 in light and #bfdbfe in dark, where the slider previously stayed teal. --p-primary-color tracks the override in both schemes. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LyYwdsJiGLEyRrJ6tVdnpK
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Change summary
Docs only. Overriding the brand palette already works. Nothing documented it, and it takes two ramps.
Set both in your own CSS, after the library import:
--color-brand-100..1000bg-brand-*/text-brand-*--color-default-bcc-100..1000ctx-brand-*context utilities. Mode-aware, so dark mode reverses itMiss the second and the
ctx-brand-*contexts stay teal while the rest of the UI changes.PrimeVue components
Testing this in a product turned up a gap: with both ramps set,
--p-primary-colorstayed#014d49. The PrimeVue preset in@bcc-code/design-tokensdefinedprimitive.color.brandas literal hex, so--p-primary-*never read--color-brand-*. Ten components kept the teal — slider, rating, knob, datatable, treetable, tree, editor, timeline, galleria, fileupload — along with the overlay selection highlight.design-tokens 5.2.10 points
primitive.color.brandat the CSS variables and fixes it at the source. 91ffb22 bumps the dependency, so the two ramps above are enough and no PrimeVue-specific override is needed.Changes
component-library/README.md— "Brand color" section: full example, dark mode values, where to put the blocks for each styling option.component-library/docs/foundations/Colors.mdx— "Using your own brand palette" in Foundations › Colors. Condensed, links to the Readme and to Styles › Context.llms.txtandllms-full.txtgenerate from the Storybook pages, and the Readme page inlinesREADME.md, so both sections reach the AI docs endpoints without touching the generator.Verification
Applied the README snippet verbatim to rendered components in Chromium on design-tokens 5.2.10: a primary button and a slider range both give
#1d4ed8in light and#bfdbfein dark, and stay teal without it. The slider is the check that matters here, since it was one of the ten that ignored the override on 5.2.8.Storybook builds, the llms generator's quality check passes, and all fourteen docs pages the e2e suite covers load without errors.
Colors.mdxwrites asterisks in token patterns as*, because MDX reads a pair of literal asterisks as emphasis and then fails to index the page.Change type
🤖 Generated with Claude Code
https://claude.ai/code/session_01LyYwdsJiGLEyRrJ6tVdnpK