Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Spike: Check and document how custom theming will work in the template instance #1317

Open
2 tasks
dzole0311 opened this issue Dec 11, 2024 · 0 comments
Open
2 tasks
Assignees
Labels
veda v2 VEDA Refactor Epic Work

Comments

@dzole0311
Copy link
Collaborator

dzole0311 commented Dec 11, 2024

Context

Follow-up spike after #1275 to check how custom theming (e.g changing the primary colors etc) would work from the instance side (Next.js) by passing USWDS tokens.

I recently merged a change that bundles our sass styles with the USWDS styles into one CSS file and provides it to the Next.js instance.

However, my approach followed an assumption in terms of theming (e.g. changing the primary color for a specific instance) which was that we will rely on CSS root-variables set by the ThemeProvider where the value of the root variable will be, for example, a hex code for the specific USWDS color token instead of the actual color token name (e.g. cool-red). Therefore, if we want to pass USWDS token names instead of USWDS token values from the instance side to theme VEDA UI components, the current approach should be tweaked because the CSS is already compiled and cool-red doesn't exist per se (it is compiled into a hex code).

I'll want to briefly revisit this question and draft a few PRs on how theming could work from the instance side. My current impression is that if we want to allow users to use USWDS token names (e.g cool-red) for theming from the instance side, we'll probably need to ask them to use sass + install USWDS so that their SASS configuration with the tokens can be compiled to actual css.

Acceptance Criteria

  • Try a few approaches that change some of the default USWDS tokens (e.g different colors) from the instance side
  • Document the outcome
@dzole0311 dzole0311 added the veda v2 VEDA Refactor Epic Work label Dec 11, 2024
@dzole0311 dzole0311 self-assigned this Dec 12, 2024
dzole0311 added a commit that referenced this issue Dec 19, 2024
**Related Ticket / Closes:**
#1317
**Related Next.js PR:**
developmentseed/next-veda-ui#30

### Description of Changes

Restructured the library build for local development and library build:

1. Development environment:

- When developing in the veda-ui repo, we will have full USWDS package
access
- Moved USWDS related packages under `devDependencies` and added USWDS
as a `peerDependency`

2. Library build:

- Modified the build to only bundle custom component styles
- Removed USWDS package styles from the final library bundle

### Notes & Questions About Changes

Going forward, the VEDA UI library now expects consuming apps to:

- Install USWDS as a dependency
- Configure their own USWDS theme via a `_uswds-theme.scss` config file

Furthermore, we could also expose the themed variables that @AliceR and
@sandrahoang686 created in a similar config file like the one for USWDS
(e.g. `_veda-theme.scss`) and allow instances to customize them in a
similar manner like the uswds theme. Since that's out of scope for this
PR, I'll create a follow-up issue to track it.

### Validation / Testing

1. Deployment preview:

- Component styles are correctly applied
- USWDS theming works as expected
- Style specificity is maintained (custom styles override USWDS
defaults)

2. Test in local development:

- Run `yarn dev` and check that the development environment still has
full USWDS access
- Build library (yarn build) and inspect the main.css under /lib
directory -> it should contain only custom CSS styles w/o USWDS styles
included

3. In Next.js

- See related PR with deployment preview
- Change the colors using USWDS tokens in the instances
`_uswds-theme.scss` config file -> check that the change is applied, for
example, to the header
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
veda v2 VEDA Refactor Epic Work
Projects
None yet
Development

No branches or pull requests

1 participant