docs: Add CSS custom properties documentation for developers#5525
docs: Add CSS custom properties documentation for developers#5525humancompanion-usds wants to merge 1 commit into
Conversation
|
@jamigibbs - I made an attempt to write out the instructions on how to use custom properties for developers on design.va.gov. Let me know if this is even remotely close to what you were imagining. |
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive documentation for CSS custom properties to the VA Design System developer documentation. This addresses the design.va.gov portion of issue #1630, which aims to document custom properties for developers building VA.gov applications.
Changes:
- Creates a new documentation page explaining CSS custom properties, their usage, naming conventions, and best practices
- Adds the new page to the developers section navigation
- Documents both design token custom properties and component-level custom properties
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| src/_about/developers/using-custom-properties.md | New comprehensive documentation page covering CSS custom properties usage, naming conventions, available properties, and when to use them |
| src/_about/developers/index.md | Adds "Using CSS custom properties" to the developers sub-navigation menu |
jamigibbs
left a comment
jamigibbs
left a comment
There was a problem hiding this comment.
This would be very exciting if it came to fruition! I left a few thoughts/suggestions. I think the answer to those will help refine or expand it further.
|
|
||
| ## What are CSS custom properties | ||
|
|
||
| [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) (also known as CSS variables) are entities defined by CSS authors that contain specific values to be reused throughout a document. They are set using custom property notation (e.g., `--vads-color-primary: #0071bc;`) and are accessed using the `var()` function (e.g., `color: var(--vads-color-primary);`). |
There was a problem hiding this comment.
suggestion: There will be distinct names between our existing tokens ie. --vads-color-primary and what I would imagine a system of custom properties used to customize web components ie. --vads-c-button-background-color
This paragraph is describing our existing token names which I think is intentional but they can not be used to directly customize a component externally as-is.
I'm not sure what my suggestion is but it feels like this document is trying to do two different things; explain custom properties and also explain our component-level system properties for customizing web components. It almost feels like those two things need to be two separate documents.
tl;dr Naming is hard.
| @@ -0,0 +1,156 @@ | |||
| --- | |||
| layout: documentation | |||
| title: Using CSS custom properties | |||
There was a problem hiding this comment.
thought: I think just generally calling the entire thing "custom properties" is going to be very confusing. Technically the discovery was exploring a system of custom properties.
My guess is that other design systems may have given their custom property systems a unique name for this reason (ie. Styling Hooks) to distinguish it as a special kind of way to style using custom properties.
Later on in these docs it's calling that system "Component-level custom properties" so maybe that's the answer.
| title: Using CSS custom properties | ||
| permalink: /about/developers/using-custom-properties | ||
| has-parent: /about/developers/ | ||
| intro-text: CSS custom properties (also called CSS variables) allow you to customize specific styles on VA Design System web components. |
There was a problem hiding this comment.
thought: I'm wondering if this intro text is crossing wires a little bit because our existing tokens/variables can't easily be used to style web components externally. The component styles are protected by the shadow dom.
We would need to have component level custom properties (development pending) which I think is what these docs are wanting to document but it's instead talking about two different things; custom properties (we have these already) and component-level custom properties (development pending).
So this intro text makes it sound like just any old custom property can be used to customize specific styles in the web components. That's not really the case though.
Summary
/about/developers/using-custom-propertiesIssue
Amends #1630
Note: This PR addresses the
design.va.govdocumentation portion of issue #1630. The remaining tasks (Storybook updates and component-library README updates) require work in the component-library repository by the engineering team.Testing
Preview
The documentation will be available at
/about/developers/using-custom-propertiesafter merge.Open Preview Environment