@solexllc/usx 0.1.0

package/README.md

@@ -0,0 +1,45 @@
+# @solexllc/usx
+
+Branded USX component styles (`.usx-*`) layered on top of USWDS, compiled with
+Dart Sass. This package ships Sass source only (`exports` → `src/*.scss`);
+consumers compile it with the `pkg:` importer, so there is no Sass build step.
+The only build step is regenerating the icon sprite (see **Icons** below).
+
+## Theming
+
+All design tokens come from `@solexllc/usx-theme` and are runtime-themeable via
+`--usx-*` CSS custom properties. Compile `src/index.scss` for a fully static
+build (no `var()` references), or `src/themed.scss` to enable every hook.
+See `packages/usx-theme/README.md` for the full theming guide, and the Storybook
+**Documentation → Theme → Playground** to generate a theme visually.
+
+## Icons
+
+`src/img/usx-sprite.svg` is a small sprite of custom icons USWDS doesn't ship
+(currently just `spinner`, used by `@solexllc/usx-react`'s `Spinner`). It's
+also exported as `@solexllc/usx/img/usx-sprite.svg` for direct resolution.
+Like USWDS's own `dist/img/sprite.svg`, consuming apps must copy this file
+into wherever they serve static assets from (e.g. Storybook mounts it at
+`/img/usx-sprite.svg` via `staticDirs` in `.storybook/main.js`; a Django app
+would add it to `STATICFILES_DIRS`).
+
+The sprite is generated, not hand-written. Each icon lives as its own
+standalone `<svg>` file in `src/icons/<name>.svg` (viewable directly in an
+editor or browser), and `pnpm build` (or `pnpm --filter @solexllc/usx build`)
+runs `scripts/build-sprite.mjs`, which reads every file in `src/icons/` and
+writes the combined `<symbol>` sprite to `src/img/usx-sprite.svg`. To add an
+icon: create `src/icons/<name>.svg`, add a matching `{ name, meta }` entry to
+`src/img/usx-icons.json` (used by the Documentation/Icons page's search),
+then rebuild. `pnpm --filter @solexllc/usx dev` rebuilds on every save.
+
+## Tests
+
+```sh
+pnpm test   # node test/theme-check.mjs
+```
+
+`test/theme-check.mjs` compiles both entry points and asserts: the default
+build has zero `var(--usx-*)` references; the themed build uses only bare
+`var(--usx-*)` references (no fallbacks) that all exist in the theme manifest;
+every manifest entry is consumed (or explicitly listed as unconsumed); no
+literal `null` leaks into CSS; every `derivedFrom` names a real token.

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@solexllc/usx",
+  "version": "0.1.0",
+  "description": "Compiled USWDS-based component styles for USX.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/solexconsulting/usx.git",
+    "directory": "packages/usx"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sass": "src/index.scss",
+  "exports": {
+    ".": {
+      "sass": "./src/index.scss"
+    },
+    "./themed": {
+      "sass": "./src/themed.scss"
+    },
+    "./utilities": {
+      "sass": "./src/_utilities.scss"
+    },
+    "./typography": {
+      "sass": "./src/components/_typography.scss"
+    },
+    "./img/usx-sprite.svg": "./src/img/usx-sprite.svg",
+    "./img/usx-icons.json": "./src/img/usx-icons.json"
+  },
+  "files": [
+    "src"
+  ],
+  "dependencies": {
+    "@solexllc/usx-theme": "workspace:*"
+  },
+  "scripts": {
+    "build": "node scripts/build-sprite.mjs",
+    "dev": "node scripts/build-sprite.mjs --watch",
+    "test": "node test/theme-check.mjs"
+  },
+  "devDependencies": {
+    "sass": "^1.98.0"
+  }
+}

package/src/_utilities.scss

@@ -0,0 +1,146 @@
+@use 'pkg:@solexllc/usx-theme/variables' as *;
+
+@each $color-name, $color-value in $colors {
+  @if $color-value {
+    .bg-#{$color-name} {
+      background-color: $color-value !important;
+    }
+
+    .text-#{$color-name} {
+      color: $color-value !important;
+    }
+
+    .usx-border-#{$color-name} {
+      border-color: $color-value !important;
+    }
+
+    .before-bg-#{$color-name}::before {
+      background-color: $color-value !important;
+    }
+
+    .after-bg-#{$color-name}::after {
+      background-color: $color-value !important;
+    }
+  }
+}
+
+@each $color-name, $color-value in $text-colors {
+  @if $color-value {
+    .text-#{$color-name} {
+      color: $color-value !important;
+    }
+
+    .before-bg-#{$color-name}::before {
+      background-color: $color-value !important;
+    }
+
+    .after-bg-#{$color-name}::after {
+      background-color: $color-value !important;
+    }
+  }
+}
+
+@each $color-name, $color-value in $surface-colors {
+  @if $color-value {
+    .bg-#{$color-name} {
+      background-color: $color-value !important;
+    }
+
+    .before-bg-#{$color-name}::before {
+      background-color: $color-value !important;
+    }
+
+    .after-bg-#{$color-name}::after {
+      background-color: $color-value !important;
+    }
+  }
+}
+
+.usx-rounded-sm {
+  border-radius: $usx-radius-sm;
+  overflow: clip;
+}
+
+.usx-rounded-md {
+  border-radius: $usx-radius-md;
+  overflow: clip;
+}
+
+.usx-rounded-lg {
+  border-radius: $usx-radius-lg;
+  overflow: clip;
+}
+
+.usx-rounded-xl {
+  border-radius: $usx-radius-xl;
+  overflow: clip;
+}
+
+.usx-circle {
+  border-radius: $usx-radius-full;
+  overflow: clip;
+}
+
+.usx-ping {
+  position: relative;
+
+  &::after {
+    content: '';
+    position: absolute;
+    inset: 0;
+    border-radius: inherit;
+    background-color: currentcolor;
+    animation: ping 2s cubic-bezier(0, 0, .2, 1) infinite;
+  }
+}
+
+.usx-pulse {
+  animation: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+}
+
+.usx-bounce {
+  animation: bounce 1s infinite;
+}
+
+@keyframes ping {
+  75%,
+  100% {
+    transform: scale(2);
+    opacity: 0;
+  }
+}
+
+@keyframes pulse {
+  50% {
+    opacity: 0.5;
+  }
+}
+
+@keyframes bounce {
+  0%,
+  100% {
+    transform: translateY(-25%);
+    animation-timing-function: cubic-bezier(0.8, 0, 1, 1);
+  }
+
+  50% {
+    transform: none;
+    animation-timing-function: cubic-bezier(0, 0, 0.2, 1);
+  }
+}
+
+$usx-sizes: (
+  min: min-content,
+  max: max-content,
+  fit: fit-content
+);
+
+@each $key, $value in $usx-sizes {
+  .usx-width-#{$key} {
+    width: $value;
+  }
+
+  .usx-height-#{$key} {
+    height: $value;
+  }
+}

package/src/components/_accordion.scss

@@ -0,0 +1,110 @@
+@use 'pkg:@solexllc/usx-theme/variables' as *;
+
+// Minus/plus icons as inline data URIs (copied from USWDS's own
+// usa-icons/remove.svg and usa-icons/add.svg). USWDS bakes these in as
+// fixed-color `background-image`s at build time, so they can't track a
+// runtime text-color override. Embedding them here lets us repaint them via
+// `mask-image` + `background-color` instead \u2014 no bundler asset path
+// resolution needed, and it reuses the exact same icon artwork.
+$usx-accordion-icon-remove: 'data:image/svg+xml,%3Csvg xmlns=\'http://www.w3.org/2000/svg\' width=\'24\' height=\'24\' viewBox=\'0 0 24 24\'%3E%3Cpath d=\'M19 13H5v-2h14v2z\'/%3E%3C/svg%3E';
+$usx-accordion-icon-add: 'data:image/svg+xml,%3Csvg xmlns=\'http://www.w3.org/2000/svg\' width=\'24\' height=\'24\' viewBox=\'0 0 24 24\'%3E%3Cpath d=\'M19 13h-6v6h-2v-6H5v-2h6V5h2v6h6v2z\'/%3E%3C/svg%3E';
+
+/* stylelint-disable selector-class-pattern -- Public USX classes use BEM naming. */
+.usx-accordion {
+  .usa-accordion__button {
+    border-radius: $usx-accordion-radius;
+  }
+
+  .usa-accordion__button[aria-expanded="true"] {
+    border-end-start-radius: 0;
+    border-end-end-radius: 0;
+  }
+
+  &.usa-accordion--bordered {
+    .usa-accordion__content {
+      @if $usx-accordion-border-width {
+        border-width: $usx-accordion-border-width;
+      }
+    }
+  }
+
+  .usa-accordion__content {
+    border-end-start-radius: $usx-accordion-radius;
+    border-end-end-radius: $usx-accordion-radius;
+  }
+
+  @if $usx-accordion-bg {
+    .usa-accordion__button {
+      background-color: $usx-accordion-bg;
+    }
+
+    @if $usx-accordion-bg-hover {
+      .usa-accordion__button:hover {
+        background-color: $usx-accordion-bg-hover !important;
+      }
+    }
+
+    &.usa-accordion--bordered {
+      .usa-accordion__content {
+        border-color: $usx-accordion-bg;
+      }
+    }
+  }
+
+  @if $usx-accordion-content-bg {
+    .usa-accordion__content {
+      background-color: $usx-accordion-content-bg;
+    }
+  }
+
+  @if $usx-accordion-text {
+    // Replace the frozen background-image icon with a mask painted in the
+    // same theme-aware color as the text (mirrors the technique USWDS
+    // itself uses for forced-colors mode, just applied unconditionally).
+    .usa-accordion__button {
+      color: $usx-accordion-text;
+      position: relative;
+      background-image: none !important;
+      padding-inline: $usx-accordion-icon-padding-start $usx-accordion-icon-padding-end;
+
+      &::before {
+        content: '';
+        position: absolute;
+        top: 0;
+        inset-inline: $usx-accordion-icon-position;
+        height: 100%;
+        width: 1.5rem;
+        background-color: $usx-accordion-text;
+        mask: url("#{$usx-accordion-icon-remove}") center / 1.5rem no-repeat;
+        -webkit-mask: url("#{$usx-accordion-icon-remove}") center / 1.5rem no-repeat;
+      }
+
+      &[aria-expanded="false"]::before {
+        mask-image: url("#{$usx-accordion-icon-add}");
+        -webkit-mask-image: url("#{$usx-accordion-icon-add}");
+      }
+
+      &:hover {
+        background-image: none !important;
+      }
+
+      &:hover::before {
+        background-color: $usx-accordion-text !important;
+      }
+    }
+
+    &.usa-accordion--icon-start .usa-accordion__button::before {
+      inset-inline: 1.25rem auto;
+    }
+
+    &.usa-accordion--icon-end .usa-accordion__button::before {
+      inset-inline: auto 1.25rem;
+    }
+  }
+
+  @if $usx-accordion-content-text {
+    .usa-accordion__content {
+      color: $usx-accordion-content-text;
+    }
+  }
+}

package/src/components/_alert.scss

@@ -0,0 +1,156 @@
+@use "sass:string";
+@use 'pkg:@solexllc/usx-theme/variables' as *;
+
+/* stylelint-disable selector-class-pattern, no-descending-specificity -- Public USX classes use BEM naming; intentional cascade order. */
+
+// For alerts that aren't under usx-site-alert
+.usa-alert:not(.usx-site-alert *) {
+	&.usx-alert, .usa-alert__body {
+		position: relative;
+
+		@if $usx-alert-radius {
+			border-radius: $usx-alert-radius;
+		}
+
+		@if $usx-alert-box-shadow {
+			box-shadow: $usx-alert-box-shadow;
+		}
+	}
+}
+
+.usx-alert__dismiss {
+	padding: 6px;
+	width: 2.5rem;
+	height: 2.5rem;
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	appearance: none;
+	border: none;
+	cursor: pointer;
+	background: transparent;
+	position: absolute;
+	color: currentcolor;
+	top: 0;
+	right: 0;
+	margin: 0;
+	z-index: 1;
+}
+
+@mixin usx-alert-variant($name, $bg, $color, $link-color, $border) {
+	$uswds-class-name: string.unquote("usa-alert--#{$name}");
+	$usa-class-name: string.unquote("usa-alert--#{$name}");
+
+	.#{$uswds-class-name}.#{$usa-class-name}:not(.usx-site-alert--maintenance *):not(.usx-site-alert--maintenance-warning *),
+	.#{$uswds-class-name}.#{$usa-class-name}:not(.usx-site-alert--maintenance *):not(.usx-site-alert--maintenance-warning *) .usa-alert__body {
+		@if $bg {
+			background-color: $bg;
+		}
+
+		@if $color {
+			color: $color;
+
+			::before {
+				background-color: $color;
+			}
+		}
+
+		@if $link-color {
+			.usa-link {
+				color: $link-color;
+			}
+		}
+
+		@if $border {
+			border-color: $border;
+		}
+
+		@if $usx-alert-border-width {
+			border-width: $usx-alert-border-width;
+		}
+	}
+}
+
+/* Info variant */
+@include usx-alert-variant("info",
+	$usx-alert-info-bg,
+	$usx-alert-info-text,
+	$usx-alert-info-link-text,
+	$usx-alert-info-border);
+
+/* Warning variant */
+@include usx-alert-variant("warning",
+	$usx-alert-warning-bg,
+	$usx-alert-warning-text,
+	$usx-alert-warning-link-text,
+	$usx-alert-warning-border);
+
+/* Success variant */
+@include usx-alert-variant("success",
+	$usx-alert-success-bg,
+	$usx-alert-success-text,
+	$usx-alert-success-link-text,
+	$usx-alert-success-border);
+
+/* Error variant */
+@include usx-alert-variant("error",
+	$usx-alert-error-bg,
+	$usx-alert-error-text,
+	$usx-alert-error-link-text,
+	$usx-alert-error-border);
+
+/* Emergency variant */
+@include usx-alert-variant("emergency",
+	$usx-alert-emergency-bg,
+	$usx-alert-emergency-text,
+	$usx-alert-emergency-link-text,
+	$usx-alert-emergency-border);
+
+
+.usx-alert {
+	.usa-alert--slim {
+		@if $usx-alert-slim-padding-block {
+			padding-block: $usx-alert-slim-padding-block;
+		}
+
+		@if $usx-alert-slim-padding-inline {
+			padding-inline: $usx-alert-slim-padding-inline;
+		}
+	}
+
+	.usa-alert--no-icon {
+		@if $usx-alert-no-icon-padding-inline-start {
+			padding-inline-start: $usx-alert-no-icon-padding-inline-start;
+		}
+	}
+
+	.usa-alert__body {
+		@if $usx-alert-body-gap {
+			gap: $usx-alert-body-gap;
+		}
+	}
+
+	.usa-alert__heading {
+		@if $usx-alert-heading-font-size {
+			font-size: $usx-alert-heading-font-size;
+		}
+
+		@if $usx-alert-heading-font-weight {
+			font-weight: $usx-alert-heading-font-weight;
+		}
+
+		@if $usx-alert-heading-margin-block-end {
+			margin-block-end: $usx-alert-heading-margin-block-end;
+		}
+	}
+
+	.usa-alert__text {
+		@if $usx-alert-text-font-size {
+			font-size: $usx-alert-text-font-size;
+		}
+
+		@if $usx-alert-text-line-height {
+			line-height: $usx-alert-text-line-height;
+		}
+	}
+}

package/src/components/_attribution.scss

@@ -0,0 +1,40 @@
+@use 'pkg:@solexllc/usx-theme/variables' as *;
+
+/* stylelint-disable selector-class-pattern -- Public USX classes use BEM naming. */
+.usx-attribution {
+  display: flex;
+  align-items: center;
+  column-gap: 1rem;
+
+  .usx-attribution__media {
+    flex: 0 0 auto;
+    display: inline-flex;
+    align-items: center;
+  }
+
+  .usx-attribution__content {
+    min-width: 0;
+    display: flex;
+    flex-direction: column;
+    row-gap: 0;
+  }
+
+  .usx-attribution__primary,
+  .usx-attribution__secondary {
+    margin: 0;
+    line-height: $usx-line-height-heading;
+  }
+
+  .usx-attribution__primary {
+    font-weight: $usx-attribution-primary-font-weight;
+  }
+
+  .usx-attribution__secondary {
+    font-size: $usx-attribution-secondary-font-size;
+    color: #71767a;
+
+    @if $usx-attribution-secondary-text {
+      color: $usx-attribution-secondary-text;
+    }
+  }
+}

package/src/components/_avatar-group.scss

@@ -0,0 +1,50 @@
+@use 'pkg:@solexllc/usx-theme/variables' as *;
+
+/* stylelint-disable selector-class-pattern -- Public USX classes use BEM naming. */
+/* stylelint-disable no-descending-specificity -- Intentional cascade order for avatar overlap/stacked modifiers. */
+.usx-avatar-group {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+
+  &.usa-avatar-group--overlap {
+    &:not(.usa-avatar-group--stacked) {
+      .usx-avatar:not(:first-child) {
+        margin-left: -1.5rem;
+
+        @if $usx-avatar-group-overlap-size {
+          margin-left: -$usx-avatar-group-overlap-size;
+        }
+      }
+    }
+
+    .usx-avatar {
+      &:hover {
+        z-index: 1;
+
+        img {
+          box-shadow: 0 0 0 2px #00bde3;
+
+          @if $usx-avatar-group-overlap-box-shadow {
+            box-shadow: $usx-avatar-group-overlap-box-shadow;
+          }
+        }
+      }
+    }
+  }
+
+  &.usa-avatar-group--stacked {
+    flex-direction: column;
+    align-items: start;
+
+    &.usa-avatar-group--overlap {
+      .usx-avatar:not(:first-child) {
+        margin-top: -1rem;
+      }
+    }
+  }
+
+  .usx-avatar {
+    margin: 0;
+  }
+}

package/src/components/_avatar.scss

@@ -0,0 +1,63 @@
+@use 'pkg:@solexllc/usx-theme/variables' as *;
+
+/* stylelint-disable selector-class-pattern -- Public USX classes use BEM naming. */
+/* stylelint-disable no-descending-specificity -- Size modifiers intentionally precede the base content rule. */
+.usx-avatar {
+  text-decoration: none;
+  display: block;
+  width: 3rem;
+  height: 3rem;
+
+  &.usx-avatar--size-sm {
+    width: 2.5rem;
+    height: 2.5rem;
+
+    .usx-avatar__content {
+      font-size: $usx-avatar-font-size-sm;
+    }
+  }
+
+  &.usx-avatar--size-md {
+    width: 3rem;
+    height: 3rem;
+  }
+
+  &.usx-avatar--size-lg {
+    width: 4rem;
+    height: 4rem;
+
+    .usx-avatar__content {
+      font-size: $usx-avatar-font-size-lg;
+    }
+  }
+
+  &.usx-avatar--size-xl {
+    width: 5rem;
+    height: 5rem;
+
+    .usx-avatar__content {
+      font-size: $usx-avatar-font-size-xl;
+    }
+  }
+
+  .usx-avatar__img {
+    height: 100%;
+    width: 100%;
+    object-fit: cover;
+  }
+
+  .usx-avatar__content {
+    width: 100%;
+    height: 100%;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    font-weight: $usx-avatar-content-font-weight;
+    line-height: 1;
+
+    .usa-icon {
+      width: 60%;
+      height: 60%;
+    }
+  }
+}

package/src/components/_banner.scss

@@ -0,0 +1,30 @@
+@use 'pkg:@solexllc/usx-theme/variables' as *;
+
+/* stylelint-disable selector-class-pattern -- Public USX classes use BEM naming. */
+.usa-banner.usx-banner {
+  @if $usx-banner-bg {
+    background-color: $usx-banner-bg;
+  }
+
+  @if $usx-banner-text {
+    color: $usx-banner-text;
+  }
+
+  .usa-banner__header-text, .usa-banner__content {
+    @if $usx-banner-text {
+      color: $usx-banner-text;
+    }
+  }
+
+  .usa-banner__button {
+    @if $usx-banner-button-text {
+      color: $usx-banner-button-text;
+    }
+  }
+
+  .usa-banner__button::after {
+    @if $usx-banner-chevron-text {
+      background-color: $usx-banner-chevron-text;
+    }
+  }
+}