(#1876, #2086) Create ncids cdns

.github/workflows/generate-bs-images.yml

@@ -9,6 +9,9 @@ jobs:
         image: httpd:2.4
         ports:
           - 8080:80
+    permissions:
+      contents: read
+      packages: read
     steps:
       ## This clones and checks out.
       - name: Checkout branch

.github/workflows/ocpl_cm_standards_check.yml

@@ -7,3 +7,5 @@ on:
 jobs:
   commitlint_remote:
     uses: nciocpl/.github/.github/workflows/ocpl_cm_standards_check.yml@workflow/v2
+    permissions:
+      contents: read

.github/workflows/workflow.yml

@@ -21,6 +21,10 @@ jobs:
         image: httpd:2.4
         ports:
           - 8080:80
+    permissions:
+      contents: read
+      packages: read
+      pull-requests: write
     steps:
       ## Setup variables for build info
       - name: Set Variables
@@ -133,6 +137,9 @@ jobs:
           ## be in netstorage for designsystem-dev. NOTE: this should **still** get
           ## set for production builds, but without the build_name.
           EXAMPLE_SITE_PUBLIC_PATH: ${{ format('/{0}/example-site', steps.set_vars.outputs.build_name) }}
+          ## The for dev cdn will be something like /cdn/pr-1234/ncids-css/ncids.min.css.
+          ## For prod the cdn will be something like /cdn/v3.4.0/ncids-css/ncids.min.css.
+          EXAMPLE_SITE_CDN_BASE_PATH: ${{ format('/cdn/{0}', steps.set_vars.outputs.build_name) }}
           ## This is used by the SitewideSearchApp and NEEDs to be the path that will ultimately
           ## be in netstorage for designsystem-dev. NOTE: this should **still** get
           ## set for production builds, but without the build_name.
@@ -188,20 +195,22 @@ jobs:
       #        with:
       #          name: test-results
       #          path: coverage
-      ## Upload the test results artifact
+      ## Upload the documentation site
       - name: Archive production artifacts
         uses: actions/upload-artifact@v4
         with:
           name: documentation-site
           path: dist/documentation-site/
           include-hidden-files: true
   deploy-doc-site:
-    name: Deploy documentation site to dev server
+    name: Deploy documentation site and downloads to dev server
     ## Only do this if the repo is NCIOCPL
     if: startsWith(github.repository, 'NCIOCPL')
     ## This job depends on build completing
     needs: build
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     steps:
       - name: Download built site
         uses: actions/download-artifact@v4
@@ -247,6 +256,24 @@ jobs:
           local-path: ${{ format('{0}.zip', env.BUILD_NAME) }}
           ## Note this action automatically prepends the cpcode to the path.
           destination-path: ${{ format('/{0}.zip', env.BUILD_NAME) }}
+      # The CDN artifact is named with the version from package-lock so we need to find that to upload it.
+      - name: Get CDN artifact name
+        id: cdn-name
+        run: |
+          FILE=$(ls documentation-site/downloads/ncids-v*.zip 2>/dev/null | head -n 1)
+          FILENAME=$(basename "$FILE")
+          echo "filename=$FILENAME" >> "$GITHUB_OUTPUT"
+      - name: Upload CDN artifact to netstorage
+        uses: nciocpl/[email protected]
+        with:
+          hostname: ${{ secrets.ns_hostname }}
+          cp-code: ${{ secrets.ns_cdn_cpcode }}
+          key-name: ${{ secrets.ns_keyname }}
+          key: ${{ secrets.ns_key }}
+          index-zip: true
+          local-path: ${{ format('documentation-site/downloads/{0}', steps.cdn-name.outputs.filename) }}
+          ## Note this action automatically prepends the cpcode to the path.
+          destination-path: ${{ format('/{0}.zip', env.BUILD_NAME, steps.cdn-name.outputs.filename) }}
       - name: Clear Site Cache
         uses: nciocpl/[email protected]
         with:
@@ -255,4 +282,4 @@ jobs:
           client-secret: ${{ secrets.eg_client_secret }}
           access-token: ${{ secrets.eg_access_token }}
           type: "cpcodes"
-          ref: ${{ format('{0},{1}', secrets.ns_cpcode, secrets.prop_cpcode) }}
+          ref: ${{ format('{0},{1},{2}', secrets.ns_cpcode, secrets.ns_cdn_cpcode, secrets.prop_cpcode) }}

.gitignore

@@ -109,3 +109,5 @@ dist
 # ide
 .idea/*
 .vscode/settings.json
+
+cdn/

docs/content/get-started/developers.mdx

@@ -9,29 +9,29 @@ meta_description: |
 
 # Getting Started for Developers
 
-To get started using the NCI Design System (NCIDS), developers will go through three phases: installing, compiling, and customizing the code. This page provides a step-by-step guide, taking developers through the process of each of these phases. Please reference our [contact information](/about#contact-us) if additional support is needed.
+Get started using the NCI Design System (NCIDS) by installing Node and npm (recommended), using a Content Delivery Network (CDN), or through a direct download of the NCIDS files.
 
-- [Step 1: Install](#step-1-install-node-and-npm)
-- [Step 2: Compile and Import](#step-2-compile-and-import)
-- [Step 3: Customize](#step-3-customize)
+This page provides a step-by-step guide on how to install, compile, and customize your code using Node and npm. Options to use the CDN or a direct download of the NCIDS for your project are also provided. Please reference our [contact information](/about#contact-us) if additional support is needed.
 
-## Step 1: Install Node and npm
+## Node and npm
 
-NCIDS distributes our source code through a node package manager (npm), which uses a flavor of JavaScript called Node.js. The best way to add NCIDS to your project is with npm via a Terminal window. (Check out some tips for using Terminal on a [Mac](https://support.apple.com/guide/terminal/open-or-quit-terminal-apd5265185d-f365-44cb-8b09-71a064a42125/mac) or [Windows](https://www.microsoft.com/en-us/p/windows-terminal/9n0dx20hk701?rtc=1&activetab=pivot:overviewtab).)
+### Step 1: Install Node and npm
+
+NCIDS distributes our source code through a node package manager (npm), which uses a flavor of JavaScript called Node.js. We recommend using the NCIDS via npm because it provides more flexibility through its modular approach. The best way to add NCIDS to your project is with npm via a Terminal window. (Check out some tips for using Terminal on a [Mac](https://support.apple.com/guide/terminal/open-or-quit-terminal-apd5265185d-f365-44cb-8b09-71a064a42125/mac) or [Windows](https://www.microsoft.com/en-us/p/windows-terminal/9n0dx20hk701?rtc=1&activetab=pivot:overviewtab).)
 
 Installing the Design System with Node and npm not only allows you to install all the code the Design System needs to compile with just a couple commands, but will version any installed packages, like NCIDS, as well — meaning your project code is tied to a specific version of the Design System. Confirming what version you’re using and updating to a newer (or older) version is straightforward.
 
 To download fonts, refer to the [Typography](/foundations/typography) page.
 
-### Step 1.1: Install Node
+#### Step 1.1: Install Node
 
 1. Ensure that you have Node.js installed, preferably Node 18, to meet the required runtime environment.
 
 2. Open your Terminal application and a Terminal window. Check to see if you have Node installed with `node -v`.
 
 If you don’t have Node, we recommend installing it through a node version manager such as [Node Version Manager](https://github.com/nvm-sh/nvm) on a Mac or Linux machine, or [nvm-windows](https://github.com/coreybutler/nvm-windows) on a Windows machine. It can also be installed directly from [Node.js](https://nodejs.org/en/download/).
 
-### Step 1.2: Authenticating to the NCIDS npm registry
+#### Step 1.2: Authenticating to the NCIDS npm registry
 
 NCIDS utilizes GitHub’s npm registry to host its packages. To access and download these packages, you need to be authenticated with a valid access token.
 
@@ -66,7 +66,7 @@ NCIDS utilizes GitHub’s npm registry to host its packages. To access and downl
 
 For more details, see [authenticating with a personal access token](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry#authenticating-with-a-personal-access-token).
 
-### Step 1.3: Initialize Your Project in Node
+#### Step 1.3: Initialize Your Project in Node
 
 1. Once you have Node and npm installed, go to the root of your project directory in Terminal. The root is the topmost directory associated with your project, the directory that includes all your project files and directories. In Terminal, the root will read as follows:
 
@@ -88,7 +88,7 @@ In order to download the NCIDS, you will have to set up the @nciocpl organizatio
 @nciocpl:registry=https://npm.pkg.github.com
 ```
 
-### Step 1.4: Install NCIDS
+#### Step 1.4: Install NCIDS
 
 <div className="usa-alert usa-alert--info usa-alert--slim" role="alert">
 	<div className="usa-alert__body">
@@ -114,9 +114,9 @@ npm install @nciocpl/ncids-js
 
 **Don’t modify the source code. Now that you’ve installed the NCIDS source code, it is controlled by npm and could be rewritten at any time.**
 
-## Step 2: Compile and Import
+### Step 2: Compile and Import
 
-### Step 2.1: Use a Sass Compiler
+#### Step 2.1: Use a Sass Compiler
 
 When using NCIDS, you must use [Dart Sass](https://www.npmjs.com/package/sass)—a modern Sass compiler that can parse Sass Module syntax. This process will convert the work you’ve done on your style sheet in Sass into Cascading Style Sheet (CSS).
 
@@ -173,7 +173,7 @@ Load paths must include a path to the `/packages` directory for NCIDS packages a
 },
 ```
 
-### Step 2.2: Import the Compiled Package
+#### Step 2.2: Import the Compiled Package
 
 This next step consists of creating the Sass style sheet. For more detailed instructions on how to setup your project, visit our [example app repository](https://github.com/NCIOCPL/ncids-example-sites).
 
@@ -222,8 +222,94 @@ The @use and @forward directives are used to import and manage Sassy Cascading S
 
 **Note:** The load paths option for importing Sass partials or modules is specific to **Dart Sass**. If you're using another Sass implementation, such as Node Sass, LibSass, or Ruby Sass, the load paths option may not be available. Make sure to use the appropriate load path mechanism specific to your chosen Sass implementation.
 
-## Step 3: Customize
+### Step 3: Customize
 
 Customize the design system with settings and custom code.
 
 The USWDS [Settings](https://designsystem.digital.gov/documentation/settings/) page describes each of the settings available in the settings files, as well as the values the settings accept. Most settings accept design tokens. Visit the [Foundations](/foundations) section of our website for more information on the available tokens for color, spacing units, font size, and more.
+
+## Content Delivery Network
+
+While using the NCIDS via npm is recommended, there are three options to use the NCIDS via Content Delivery Network (CDN) - these options include using the NCIDS Minimal, NCIDS without utilities, and NCIDS with utilities. Choose the option that works best for your use case.
+
+The CDN allows you to use the NCIDS without installing, compiling, or customizing the code. To do so, directly include the stylesheet and JavaScript in your HTML. Then update your HTML to utilize the NCIDS CSS classes.
+
+import useSiteMetadata from '../../src/hooks/use-site-metadata';
+import { withPrefix } from 'gatsby';
+import PropTypes from 'prop-types';
+
+export const CDNCode = ({ cssFile, jsFile }) => {
+	CDNCode.propTypes = {
+		cssFile: PropTypes.string.isRequired,
+		jsFile: PropTypes.string.isRequired,
+	};
+	const v = useSiteMetadata()?.versionInfo?.ncidsVersion ?? 'ERROR';
+	const cssPath = withPrefix(`/ncids-${v}/ncids-css/${cssFile}`);
+	const jsPath = withPrefix(`/ncids-${v}/ncids-js/${jsFile}`);
+	const snippet = `<link
+	href='https://designsystem.cancer.gov/cdn${cssPath}'
+	rel='stylesheet'
+	crossorigin='anonymous'
+/>
+<script
+	src='https://designsystem.cancer.gov/cdn${jsPath}'
+	crossorigin='anonymous'></script>`;
+	return (
+		<Code className="language-html" nopreview="true">
+			{snippet}
+		</Code>
+	);
+};
+
+### NCIDS Minimal
+
+For a minimal configuration of the NCIDS, use the tags below:
+
+<CDNCode cssFile="ncids-minimal.min.css" jsFile="ncids-minimal.min.js" />
+
+### NCIDS Without Utilities
+
+For the standard configuration of the NCIDS, but without utilities, use the tags below:
+
+<CDNCode cssFile="ncids.min.css" jsFile="ncids.min.js" />
+
+### NCIDS With Utilities
+
+For the full configuration of the NCIDS, including utilities, use the tags below:
+
+<CDNCode cssFile="ncids-full.min.css" jsFile="ncids-full.min.js" />
+
+## Direct Download
+
+You can download the NCIDS files to use on your site. Simply include the NCIDS folder in your website assets and add the stylesheet and JavaScript to your pages directly.
+
+export const DownloadLink = () => {
+	const v = useSiteMetadata()?.versionInfo?.ncidsVersion ?? 'ERROR';
+	const href = withPrefix(`/downloads/ncids-${v}.zip`);
+	return (
+		<a href={href} download>
+			ncids-{v}.zip
+		</a>
+	);
+};
+
+export const DownloadCode = () => {
+	const v = useSiteMetadata()?.versionInfo?.ncidsVersion ?? 'ERROR';
+	const snippet = `<link
+	href='your/assets/path/ncids-${v}/ncids.min.css'
+	rel='stylesheet'
+/>
+<script
+	src='your/assets/path/ncids-${v}/ncids.min.js'></script>`;
+	return (
+		<Code className="language-html" nopreview="true">
+			{snippet}
+		</Code>
+	);
+};
+
+Download here: <DownloadLink />.
+
+<DownloadCode />
+
+In the zip file, you will find the same three versions available as on the CDN: minimal, without utilities, and with utilities.

docs/src/index.scss

@@ -17,7 +17,7 @@
 		"widescreen": true
 	)
 );
-@forward "ncids";
+@forward "ncids-full";
 @forward "usa-prose";
 @forward "usa-table";
 @forward "usa-icon";

package.json

@@ -19,8 +19,8 @@
     "build": "lerna run build",
     "clean:build": "lerna run clean:build",
     "docs-artifact": "pnpm run docs-artifact:build && rimraf dist && pnpm run docs-artifact:copy",
-    "docs-artifact:build": "lerna run clean:build && pnpm run gatsby:build && pnpm run storybook:build && pnpm run example-site:build && pnpm run js-docs:build",
-    "docs-artifact:copy": "mkdirp dist/documentation-site && pnpm run gatsby:copy && pnpm run storybook:copy && pnpm run example-site:copy && pnpm run js-docs:copy",
+    "docs-artifact:build": "lerna run clean:build && pnpm run gatsby:build && pnpm run storybook:build && pnpm run example-site:build && pnpm run js-docs:build && pnpm run cdn:build",
+    "docs-artifact:copy": "mkdirp dist/documentation-site && pnpm run gatsby:copy && pnpm run storybook:copy && pnpm run example-site:copy && pnpm run js-docs:copy && pnpm run cdn:copy",
     "gatsby:build": "lerna run build --scope=nci-design-system --include-dependencies",
     "gatsby:copy": "ncp docs/public dist/documentation-site",
     "example-site:build": "lerna run build --scope=ncids-js-testing --include-dependencies",
@@ -29,7 +29,9 @@
     "js-docs:copy": "mkdirp dist/documentation-site/ncids-js && ncp packages/ncids-js/doc dist/documentation-site/ncids-js",
     "storybook:build": "lerna run build --scope=ncids-css-testing --include-dependencies",
     "storybook:copy": "mkdirp dist/documentation-site/storybook && ncp testing/ncids-css-testing/storybook-static dist/documentation-site/storybook",
-    "test": "lerna run test",
+		"cdn:build": "mkdirp cdn && ./scripts/zip-builds.sh",
+		"cdn:copy": "mkdirp dist/documentation-site/downloads && ncp cdn dist/documentation-site/downloads",
+		"test": "lerna run test",
     "test:css": "lerna run test:css",
     "test:a11y": "lerna run test:a11y",
     "test:css:generate": "lerna run test:css:generate",

packages/ncids-css/entrypoints/ncids-full.scss

@@ -0,0 +1,17 @@
+@use "uswds-core" with (
+ $theme-image-path: "../uswds-img",
+ $theme-show-notifications: false,
+ $theme-show-compile-warnings: false,
+ $theme-utility-breakpoints: (
+  "card": false,
+  "card-lg": false,
+  "mobile": false,
+  "mobile-lg": true,
+  "tablet": true,
+  "tablet-lg": true,
+  "desktop": true,
+  "desktop-lg": false,
+  "widescreen": true
+ ),
+);
+@forward "packages/ncids-full";

packages/ncids-css/entrypoints/ncids-minimal.scss

@@ -0,0 +1,17 @@
+@use "uswds-core" with (
+ $theme-image-path: "../uswds-img",
+ $theme-show-notifications: false,
+ $theme-show-compile-warnings: false,
+ $theme-utility-breakpoints: (
+  "card": false,
+  "card-lg": false,
+  "mobile": false,
+  "mobile-lg": true,
+  "tablet": true,
+  "tablet-lg": true,
+  "desktop": true,
+  "desktop-lg": false,
+  "widescreen": true
+ ),
+);
+@forward "packages/ncids-minimal";

packages/ncids-css/entrypoints/ncids.scss

@@ -0,0 +1,17 @@
+@use "uswds-core" with (
+ $theme-image-path: "../uswds-img",
+ $theme-show-notifications: false,
+ $theme-show-compile-warnings: false,
+ $theme-utility-breakpoints: (
+  "card": false,
+  "card-lg": false,
+  "mobile": false,
+  "mobile-lg": true,
+  "tablet": true,
+  "tablet-lg": true,
+  "desktop": true,
+  "desktop-lg": false,
+  "widescreen": true
+ ),
+);
+@forward "packages/ncids";