Add Starlight documentation app and centralize USWDS initialization#5
Merged
mbwatson merged 14 commits intostagecc:mainfrom Feb 23, 2026
Merged
Add Starlight documentation app and centralize USWDS initialization#5mbwatson merged 14 commits intostagecc:mainfrom
mbwatson merged 14 commits intostagecc:mainfrom
Conversation
install deps
…ght docs
- Create packages/ui with shared generic components extracted from apps/site:
Button, Card, Icon, Link, BlockLink, TagLink, Breadcrumbs,
YouTubeEmbed, Testimonial
- Update all apps/site imports to consume components from @bdc/ui
instead of local @components/ aliases
- Configure apps/docs (Starlight) to use shared USWDS design tokens:
- Add @bdc/uswds-theme, @uswds/uswds, and sass-embedded dependencies
- Add custom.scss that compiles uswds-core with shared theme settings
and maps USWDS tokens to Starlight CSS custom properties
- Add vite scss loadPaths for USWDS package resolution
Both apps now share design tokens from @bdc/uswds-theme and can share
UI primitives from @bdc/ui.
Co-authored-by: Amp <amp@ampcode.com>
What was removed: index.scss (unused entry point) and _components.scss (forwarded USWDS component packages already included by @use "uswds"). What changed: _uswds-init.scss now @forwards the settings variables, so consumers only need one import (@use "uswds-init" as theme) to get both the core-* functions and the $theme-* variables.
lint fix docs favicon
suejinkim20
approved these changes
Feb 23, 2026
Collaborator
suejinkim20
left a comment
suejinkim20
left a comment
There was a problem hiding this comment.
Pulled and tested locally:
- Confirmed
@bdc/siteand@bdc/docsrun successfully - Verified USWDS styles are applied in both apps and that changes to shared theme tokens propagate correctly
- Checked docs sidebar/navigation and light/dark mode behavior
Everything looks good, especially that docs site dark mode! 👏🏼
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
2 participants
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.
Description:
This PR adds a documentation site at
apps/docsusing Astro Starlight and refactors how USWDS is initialized so both apps share the same design tokens. Stubbed documentation pages are introduced to get navigation generated and to get a sense of user flow, but their content isn't migrated yet.What changed:
apps/docs: New Starlight-based docs app with full sidebar structure, USWDS-themed accent colors and typography mapped to Starlight CSS custom properties (with light/dark mode support). Stubbed doc pages (from existing gitbook) are also included.packages/uswds-theme: Added_uswds-init.scss, which configures and forwards uswds-core with all BDC settings in one place. Both apps now import this instead of duplicating the@use "uswds-core" with (...)boilerplate. Removed the unusedtokens.json.apps/site: Simplified global.scss to use the new shared init. Moved logo/sprite assets intosrc/assets/.Validating:
This is essentially setting up the Docs site boilerplate, so content doesn't need to be accurate at this point. What matters is that
npm run dev -w @bdc/siteandnpm run dev -w @bdc/docsboth work, as well as their builds, and USWDS styles are coming through to both apps.Validating styles are working is easily seen by changing values in
packages/uswds-theme/src/_colors.scss(e.g., change all "blue"s to "red"s), and those changes should be reflected in both running apps.