Update documentation to remove formation and add css-library #3650

powellkerry · 2025-01-02T20:36:22Z

Update all references and links to formation with the correct information and links to css-library. This is needed due to formation being deprecated and no longer being used in vets-website.

Closes 3583

Note, this does not update code references to formation. That work is planned in this ticket

…ibrary

powellkerry · 2025-01-02T20:38:08Z

README.md

@@ -57,23 +57,23 @@ To add content, you will need to look into `/src` directory. This will be the so

 [Read the wiki](https://github.com/department-of-veterans-affairs/vets-design-system-documentation/wiki) to learn how to add new pages to design.va.gov, improve local search, add images, etc.

-## Testing updates to the Formation codebase on this site
+## Testing updates to the CSS-Library codebase on this site



I just updated this copy and I'm not sure if there is a better way to give these instructions or if we need to update them.

I agree I think there might be some things we need to confirm before we can give these instructions. I have a feeling that even the Formation instructions don't actually work any more.

I would lean towards removing these steps completely rather than say something that doesn't work. Should we create a follow-up ticket for writing new steps for testing? Or maybe just remove this and link to the component-library vets-website testing instructions?

@powellkerry did you happen to test the steps below to see if they work for css library? I'm specifically interested in learning if that local version thing on line 74 works, since that seems to be the key piece for connecting the two repos for local testing.

@micahchiang yes the instructions work, but it's not as easy as they imply. I had to remove the node_modules directory and run yarn in vets-design-system-documentation in order for any changes to show. I think updating the instructions to use verdaccio might be better?

powellkerry · 2025-01-02T20:41:27Z

src/_foundation/spacing-units.md

@@ -46,7 +46,13 @@ The VA follows the USWDS spacing unit tokens and then adds additional semantic t

 In order to keep spacing consistent throughout VA.gov, it is recommended you favor using the `units` functions instead of hard coding pixels (or relative units) for margins and padding.

-In order to access the spacing tokens in your project, you will need to import the [base files](https://github.com/department-of-veterans-affairs/veteran-facing-services-tools/tree/master/packages/formation/sass/base) into your project. [Here is how this site is doing that](https://github.com/department-of-veterans-affairs/vets-design-system-documentation/blob/main/src/assets/stylesheets/application.scss#L5).
+In order to access the spacing tokens in your project, you will need to import the [base files](https://github.com/department-of-veterans-affairs/component-library/tree/main/packages/css-library/src/stylesheets) into your project. 
+<!-- 


I removed this link to look at an example because the code shows code references to formation. I will leave a comment on the ticket for updating the code references to re-add this link.

This piece about spacing tokens is a little confusing because the paragraph above references a units function 🤔

Can spacing tokens be accessed directly be importing https://github.com/department-of-veterans-affairs/component-library/blob/main/packages/css-library/dist/tokens/css/variables.css?

I updated this. I think the spacing tokens can be used by importing that variables file.

powellkerry · 2025-01-02T20:48:11Z

src/_about/developers/install.md


 ```
-$formation-asset-path: '../assets';


I couldn't find a asset-path variable in css-library. Should this be updated or removed?

I'm not exactly sure where we are with the state of assets and the CSS Library. @micahchiang Do you have any thoughts on how we should update these steps for now?

I think for now, we should mark the existing stuff as deprecated, with a message that new guidance is coming soon. We should probably conduct our own spike or experiment into what is needed to get css-library working properly across a number of different projects. I can write a follow up ticket for this.

jamigibbs · 2025-01-07T14:38:08Z

.github/ISSUE_TEMPLATE/1_bug_template.md

@@ -24,7 +24,7 @@ labels: platform-design-system-team, bug

 ## Reproducing

- Formation version:
+- CSS-Library version:


A little bit of a nit here but should the name of the library be referenced as CSS Library throughout (sans dash)? I feel like this is one of those things that once we put it into stone (the documentation), it will forever be that way.

jamigibbs · 2025-01-07T14:44:22Z

README.md

@@ -57,23 +57,23 @@ To add content, you will need to look into `/src` directory. This will be the so

 [Read the wiki](https://github.com/department-of-veterans-affairs/vets-design-system-documentation/wiki) to learn how to add new pages to design.va.gov, improve local search, add images, etc.

-## Testing updates to the Formation codebase on this site
+## Testing updates to the CSS-Library codebase on this site



I agree I think there might be some things we need to confirm before we can give these instructions. I have a feeling that even the Formation instructions don't actually work any more.

I would lean towards removing these steps completely rather than say something that doesn't work. Should we create a follow-up ticket for writing new steps for testing? Or maybe just remove this and link to the component-library vets-website testing instructions?

jamigibbs · 2025-01-07T14:44:40Z

package.json

@@ -16,8 +16,7 @@
  "keywords": [
    "Vets.gov",
    "design",
-    "uswds",
-    "formation"


👋🏼 byeeee

jamigibbs · 2025-01-07T14:45:21Z

src/_about/developers/install.md

@@ -11,24 +11,21 @@ anchors:

 ## Install CSS library into your project


Should we capitalize the "L" in library while we're here?

jamigibbs · 2025-01-07T14:46:43Z

src/_about/developers/install.md


 ```
-$formation-asset-path: '../assets';


I'm not exactly sure where we are with the state of assets and the CSS Library. @micahchiang Do you have any thoughts on how we should update these steps for now?

jamigibbs

Updates are looking good to me but do you mind checking the developer > install page again? https://dev-design.va.gov/3650/about/developers/install#install-css-library-into-your-project

Do we want to keep all of those references to Formation still even if we are planning to re-write the instructions? The header of the section is talking about CSS Library so it's a mix of libraries and confusing.

Do we have a ticket yet for discovering how to install CSS Library in different scenarios outside of vets-website? (Code Pen, Code Sandbox, etc)?

jamigibbs · 2025-01-09T14:41:16Z

src/_about/developers/install.md

 permalink: /about/developers/install
 has-parent: /about/developers/
-intro-text: 
+intro-text: "New guidance in coming soon. With the deprecation of Formation and the adoption off CSS Library the design system team is in the process of creating and providing guidance on using CSS Library across different projects."
 anchors:
  - anchor: Install CSS library into your project


Capitalize the "L" in "CSS library".

I did a global search and replaced all the lower-cased "l"s, nice to be consistent ;)

…on, capitalization semantics

…ent-of-veterans-affairs/vets-design-system-documentation into 3583-update-formation-references

powellkerry · 2025-01-09T15:51:50Z

@jamigibbs I updated install.md to say formation instead of css-library. I had just reverted my changes to that file and didn't notice that it mentioned css library. Evidently when this documentation was created, they used to refer to formation as the css library...

I also created a ticket to research and rewrite this file: #3663

jamigibbs

Evidently when this was created, they used to refer to formation as the css library

Oh dear. 🫣

Update documentation and references to remove formation and add css-l…

96daa7f

…ibrary

powellkerry requested a review from a team as a code owner January 2, 2025 20:36

powellkerry temporarily deployed to development January 2, 2025 20:36 — with GitHub Actions Inactive

powellkerry commented Jan 2, 2025

View reviewed changes

jamigibbs reviewed Jan 7, 2025

View reviewed changes

refine documentation based on feedback

e25acd5

powellkerry temporarily deployed to development January 8, 2025 16:32 — with GitHub Actions Inactive

refine documentation based on feedback

92e547f

powellkerry temporarily deployed to development January 8, 2025 16:34 — with GitHub Actions Inactive

Merge branch 'main' into 3583-update-formation-references

9f6027b

powellkerry temporarily deployed to development January 8, 2025 16:38 — with GitHub Actions Inactive

jamigibbs reviewed Jan 9, 2025

View reviewed changes

powellkerry added 2 commits January 9, 2025 08:32

update to install.md to rephrase references to css-library as formati…

06b560a

…on, capitalization semantics

Merge branch '3583-update-formation-references' of github.com:departm…

6536c1b

…ent-of-veterans-affairs/vets-design-system-documentation into 3583-update-formation-references

powellkerry temporarily deployed to development January 9, 2025 15:33 — with GitHub Actions Inactive

Merge branch 'main' into 3583-update-formation-references

af46940

powellkerry deployed to development January 9, 2025 15:53 — with GitHub Actions View deployment

jamigibbs approved these changes Jan 9, 2025

View reviewed changes

powellkerry merged commit 7ecb4ed into main Jan 9, 2025
4 checks passed

powellkerry deleted the 3583-update-formation-references branch January 9, 2025 17:34

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update documentation to remove formation and add css-library #3650

Update documentation to remove formation and add css-library #3650

powellkerry commented Jan 2, 2025 •

edited

Loading

powellkerry Jan 2, 2025

jamigibbs Jan 7, 2025

micahchiang Jan 7, 2025

powellkerry Jan 7, 2025

powellkerry Jan 2, 2025

micahchiang Jan 7, 2025

powellkerry Jan 8, 2025

powellkerry Jan 2, 2025

jamigibbs Jan 7, 2025

micahchiang Jan 7, 2025

jamigibbs Jan 7, 2025

jamigibbs Jan 7, 2025

jamigibbs Jan 7, 2025

jamigibbs Jan 7, 2025 •

edited

Loading

jamigibbs Jan 7, 2025

jamigibbs left a comment

jamigibbs Jan 9, 2025 •

edited

Loading

powellkerry Jan 9, 2025

powellkerry commented Jan 9, 2025 •

edited

Loading

jamigibbs left a comment

		@@ -11,24 +11,21 @@ anchors:

		## Install CSS library into your project

Update documentation to remove formation and add css-library #3650

Update documentation to remove formation and add css-library #3650

Conversation

powellkerry commented Jan 2, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jamigibbs Jan 7, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jamigibbs left a comment

Choose a reason for hiding this comment

jamigibbs Jan 9, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

powellkerry commented Jan 9, 2025 • edited Loading

jamigibbs left a comment

Choose a reason for hiding this comment

powellkerry commented Jan 2, 2025 •

edited

Loading

jamigibbs Jan 7, 2025 •

edited

Loading

jamigibbs Jan 9, 2025 •

edited

Loading

powellkerry commented Jan 9, 2025 •

edited

Loading