USWDS-Elements: restructure tokens into tier-first directory layout (system/theme/state)

README.md

@@ -1,13 +1,13 @@
 > [!CAUTION]
-> This repository hosts development work for the HTML Web Component version of the U.S. Web Design System, called USWDS Elements (some call it USWDS 4.0). This code may not all be suitable for production use. Work on USWDS Elements is currently taking a gradual, community-driven iterative approach to development. Everything in this repository is in a different state of development, with USWDS Banner always intended to be closest to stable due to its [inclusion in the Federal Website Standards](https://standards.digital.gov/standards/banner/), which are required by the [21st Century Integrated Digital Experience Act](https://digital.gov/resources/delivering-digital-first-public-experience#what-is-21st-century-idea) (21st Century IDEA), and reinforced by [OMB Memo M-23-22]([https://bidenwhitehouse.archives.gov/omb/management/ofcio/delivering-a-digital-first-public-experience/](https://bidenwhitehouse.archives.gov/omb/management/ofcio/delivering-a-digital-first-public-experience/#III)). The documentation of each item will include its current status — for components, check the ```docs.mdx``` in ```/src/components/[usa-component-name]```. 
+> This repository hosts development work for the HTML Web Component version of the U.S. Web Design System, called USWDS Elements (some call it USWDS 4.0). This code may not all be suitable for production use. Work on USWDS Elements is currently taking a gradual, community-driven iterative approach to development. Everything in this repository is in a different state of development, with USWDS Banner always intended to be closest to stable due to its [inclusion in the Federal Website Standards](https://standards.digital.gov/standards/banner/), which are required by the [21st Century Integrated Digital Experience Act](https://digital.gov/resources/delivering-digital-first-public-experience#what-is-21st-century-idea) (21st Century IDEA), and reinforced by [OMB Memo M-23-22](<[https://bidenwhitehouse.archives.gov/omb/management/ofcio/delivering-a-digital-first-public-experience/](https://bidenwhitehouse.archives.gov/omb/management/ofcio/delivering-a-digital-first-public-experience/#III)>). The documentation of each item will include its current status — for components, check the `docs.mdx` in `/src/components/[usa-component-name]`.
 
 # USWDS Elements
 
 The [United States Web Design System](https://designsystem.digital.gov) is a toolkit of principles, guidance, and code — a library of public domain and open source user interface components and a visual style guide designed for U.S. federal government websites, but useful in many other applications.
 
 This repository contains the code for the Web Component-based version of the design system, which is currently in pre-release status. We maintain other repositories for the [current version of the design system](https://github.com/uswds/uswds), which we call USWDS Core, as well as [its documentation and website](https://github.com/uswds/uswds-site). For USWDS Core and its documentation, visit [https://designsystem.digital.gov](https://designsystem.digital.gov).
 
-We're working on incrementally building new [Web Component](https://developer.mozilla.org/en-US/docs/Web/API/Web_components)-based implementations of USWDS Core components. Once each new USWDS Elements Web Component progresses into production-ready mode, you'll be able to use them alongside existing USWDS code. You can try out the first published example of a USWDS Web Component variant now: the [USWDS Banner Web Component variant](https://designsystem.digital.gov/components/banner/#banner-web-component-2). 
+We're working on incrementally building new [Web Component](https://developer.mozilla.org/en-US/docs/Web/API/Web_components)-based implementations of USWDS Core components. Once each new USWDS Elements Web Component progresses into production-ready mode, you'll be able to use them alongside existing USWDS code. You can try out the first published example of a USWDS Web Component variant now: the [USWDS Banner Web Component variant](https://designsystem.digital.gov/components/banner/#banner-web-component-2).
 
 Contributions are now welcome, though the USWDS Elements review process prioritizes [USWDS Open Source Community member](https://github.com/uswds/uswds/blob/develop/COMMUNITY.md#communitymd) and [USWDS partnership](https://github.com/uswds/uswds/blob/develop/COMMUNITY.md#uswds-current--former-partners) contributions.
 
@@ -197,8 +197,8 @@ If you have questions about changing the pre-release tag or the release automati
 
 ## Component versions
 
-| Component    | Status                                                                       |
-| ------------ | ---------------------------------------------------------------------------- |
-| `usa-banner` | Beta (Banner only, not entire package)                                       |
-| `usa-link`   | Pre-alpha (proof-of-concept: not intended as direction, or even for release) |
+| Component    | Status                                                                          |
+| ------------ | ------------------------------------------------------------------------------- |
+| `usa-banner` | Beta (Banner only, not entire package)                                          |
+| `usa-link`   | Pre-alpha (proof-of-concept: not intended as direction, or even for release)    |
 | `usa-alert`  | Pre-alpha (proof-of-concept for architecture validation; not completely tested) |

config/style-dictionary.config.js

@@ -17,15 +17,26 @@ StyleDictionary.registerTransform({
   transform: getTokenValueWithUnit,
 });
 
+/**
+ * Builds a Style Dictionary platform config for the given output format.
+ * Output files are keyed per-tier-per-category:
+ *
+ *   css  → build/css/<tier>/<category>.css
+ *   scss → build/scss/<tier>/_<category>.scss
+ */
 function makePlatform(format) {
   return {
     transforms: ["name/uswds-theme", "value/uswds-units"],
     prefix: "usa",
     buildPath: `build/${format}/`,
-    files: tokenGroups.map((group) => ({
-      destination: format === "scss" ? `_${group}.scss` : `${group}.css`,
+    files: tokenGroups.map(({ tier, category }) => ({
+      destination:
+        format === "scss"
+          ? `${tier}/_${category}.scss`
+          : `${tier}/${category}.css`,
       format: `${format}/variables`,
-      filter: (token) => token.filePath?.includes(`tokens/${group}/`),
+      filter: (token) =>
+        token.filePath?.includes(`tokens/${tier}/${category}/`),
     })),
   };
 }

internals/token-helpers/index.test.ts

@@ -87,6 +87,50 @@ describe("generateTokenName", () => {
     );
     expect(result).toBe("usa-font-base-size");
   });
+
+  it("should strip the 'system' tier segment from path (ADR-0010)", () => {
+    const result = generateTokenName(
+      createToken({
+        filePath: "tokens/system/color/blue.json",
+        path: ["system", "color", "blue", "5"],
+      }),
+      options,
+    );
+    expect(result).toBe("usa-color-blue-5");
+  });
+
+  it("should strip the 'system' tier segment for breakpoints (ADR-0010)", () => {
+    const result = generateTokenName(
+      createToken({
+        filePath: "tokens/system/breakpoints/breakpoints.json",
+        path: ["system", "breakpoint", "desktop-lg"],
+      }),
+      options,
+    );
+    expect(result).toBe("usa-breakpoint-desktop-lg");
+  });
+
+  it("should strip the 'theme' tier segment from path (ADR-0010)", () => {
+    const result = generateTokenName(
+      createToken({
+        filePath: "tokens/theme/color/primary.json",
+        path: ["theme", "color", "primary"],
+      }),
+      options,
+    );
+    expect(result).toBe("usa-color-primary");
+  });
+
+  it("should strip the 'state' tier segment from path (ADR-0010)", () => {
+    const result = generateTokenName(
+      createToken({
+        filePath: "tokens/state/color/error.json",
+        path: ["state", "color", "error"],
+      }),
+      options,
+    );
+    expect(result).toBe("usa-color-error");
+  });
 });
 
 describe("getTokenValueWithUnit", () => {

internals/token-helpers/index.ts

@@ -1,10 +1,22 @@
 import type { TransformedToken, PlatformConfig } from "style-dictionary/types";
 
+/**
+ * Tier path segments.
+ * generateTokenName strips these from `token.path` before joining so that the
+ * tier is organizational (directory / `$extensions.uswds.tier`) but does NOT
+ * appear in the emitted CSS custom property or Sass variable name.
+ *
+ * Example: ["system","color","blue","5"] → "usa-color-blue-5"  (tier stripped)
+ *          ["color","blue","5"]          → "usa-color-blue-5"  (no-op — unchanged)
+ */
+const TIERS = new Set(["system", "theme", "state"]);
+
 export const generateTokenName = (
   token: TransformedToken,
   options: PlatformConfig,
 ) => {
-  return `${options.prefix}-${token.path.join("-")}`;
+  const segments = token.path.filter((s) => !TIERS.has(s));
+  return `${options.prefix}-${segments.join("-")}`;
 };
 
 export const getTokenValueWithUnit = (token: TransformedToken) => {