From f6c622e4f2fe710867d288736f51b3ad3fde9203 Mon Sep 17 00:00:00 2001
From: Zlodej43sm <8863227+Zlodej43sm@users.noreply.github.com>
Date: Tue, 20 Oct 2026 15:26:31 +0200
Subject: [PATCH 1/3] refactor: add Components parent tier to Web Components
 Storybook structure

Nest Atoms, Molecules, and Layout & Structure under a Components parent category in Web Components Storybook. Add migration utilities for redirecting legacy and interim tier URLs to the new nested structure. Update story paths, link validation, smoke tests, and documentation to reflect the Components/tier/component hierarchy.
---
 bin/storybook/check-links.mjs             |  6 +-
 bin/storybook/link-validation.test.mjs    | 22 +++++--
 bin/storybook/native-checks.mjs           | 65 ++++++++++---------
 bin/storybook/routes.d.mts                |  3 +
 bin/storybook/routes.mjs                  | 38 ++++++++++-
 bin/storybook/routes.test.mjs             | 79 +++++++++++++++++++++--
 bin/storybook/smoke-test.mjs              |  6 +-
 bin/storybook/story-parity.mjs            |  8 +--
 libs/ui/.storybook/main.ts                | 17 ++++-
 libs/ui/.storybook/preview.ts             |  7 +-
 libs/ui/llms.txt                          |  2 +-
 libs/ui/src/ai/README.md                  |  2 +-
 libs/web-components/.storybook/main.ts    | 11 +++-
 libs/web-components/.storybook/preview.ts |  2 +-
 libs/web-components/README.md             | 66 +++++++++----------
 15 files changed, 236 insertions(+), 98 deletions(-)

diff --git a/bin/storybook/check-links.mjs b/bin/storybook/check-links.mjs
index 52752f4..fb341cb 100644
--- a/bin/storybook/check-links.mjs
+++ b/bin/storybook/check-links.mjs
@@ -3,7 +3,7 @@ import { existsSync, mkdtempSync, readFileSync, readdirSync, rmSync } from 'node
 import { tmpdir } from 'node:os';
 import { extname, join, relative, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { legacyReactIds, sharedDocIds } from './routes.mjs';
+import { legacyReactIds, sharedDocIds, migratedReactId } from './routes.mjs';
 import { validateLinks } from './link-validation.mjs';
 
 const root = fileURLToPath(new URL('../../', import.meta.url));
@@ -49,7 +49,7 @@ if (built) {
 
 const errors = [];
 for (const id of legacyReactIds) {
-  const canonical = sharedDocIds.includes(id) ? id : `react-${id}`;
+  const canonical = sharedDocIds.includes(id) ? id : migratedReactId(id);
   if (!indexes.react.entries[canonical]) errors.push(`Missing migrated entry: ${canonical}`);
 }
 for (const id of sharedDocIds) {
@@ -74,7 +74,7 @@ for (const [group, names] of [
   for (const name of names) {
     const primaryStory = name === 'input' ? 'primary-default-with-label-and-helper-text' : 'default';
     for (const variant of ['docs', primaryStory]) {
-      const id = `${group}-${name}--${variant}`;
+      const id = `components-${group}-${name}--${variant}`;
       if (!indexes.webComponents.entries[id]) errors.push(`Missing native Web Components entry: ${id}`);
     }
   }
diff --git a/bin/storybook/link-validation.test.mjs b/bin/storybook/link-validation.test.mjs
index fb8bc5d..abec66f 100644
--- a/bin/storybook/link-validation.test.mjs
+++ b/bin/storybook/link-validation.test.mjs
@@ -5,35 +5,43 @@ import { validateLinks } from './link-validation.mjs';
 const indexes = {
   react: {
     entries: {
-      'react-atoms-button--docs': { type: 'docs' },
+      'react-components-atoms-button--docs': { type: 'docs' },
       'theme-tokens-colors--docs': { type: 'docs' },
     },
   },
-  webComponents: { entries: { 'introduction-overview--overview': { type: 'story' } } },
+  webComponents: {
+    entries: {
+      'introduction-overview--overview': { type: 'story' },
+      'components-atoms-button--default': { type: 'story' },
+    },
+  },
 };
 
 test('validates canonical, composed and child deep links', () => {
   const result = validateLinks(
     `
-    [Button](?path=/docs/react-atoms-button--docs)
+    [Button](?path=/docs/react-components-atoms-button--docs)
     [Colors](?path=/docs/theme-tokens-colors--docs)
     https://storybook.cto-rnd-system-design.griddynamics.net/web-components/?path=/story/introduction-overview--overview
     ?path=/story/web-components_introduction-overview--overview
-    iframe.html?id=react-atoms-button--docs&viewMode=docs
+    ?path=/story/web-components_components-atoms-button--default
+    iframe.html?id=react-components-atoms-button--docs&viewMode=docs
   `,
     indexes
   );
-  assert.equal(result.checked, 5);
+  assert.equal(result.checked, 6);
   assert.deepEqual(result.errors, []);
 });
 
 test('catches stale, nonexistent, incorrectly typed and bare routes', () => {
   for (const href of [
     '?path=/docs/atoms-button--docs',
+    '?path=/docs/react-atoms-button--docs',
+    '?path=/story/web-components_atoms-button--default',
     '?path=/docs/react-nonexistent--docs',
     '?path=/docs/react-theme-tokens-colors--docs',
-    '?path=/story/react-atoms-button--docs',
-    '/docs/react-atoms-button--docs',
+    '?path=/story/react-components-atoms-button--docs',
+    '/docs/react-components-atoms-button--docs',
   ])
     assert.ok(validateLinks(href, indexes).errors.length > 0, href);
 });
diff --git a/bin/storybook/native-checks.mjs b/bin/storybook/native-checks.mjs
index d37fbf7..58db51d 100644
--- a/bin/storybook/native-checks.mjs
+++ b/bin/storybook/native-checks.mjs
@@ -6,7 +6,8 @@ export async function checkNativeStories(page, base) {
   const stories = Object.values(index.entries).filter(
     (entry) =>
       entry.type === 'story' &&
-      (/^(Atoms|Molecules)\//.test(entry.title) || entry.title.startsWith('Layout & Structure/')) &&
+      (/^Components\/(Atoms|Molecules)\//.test(entry.title) ||
+        entry.title.startsWith('Components/Layout & Structure/')) &&
       !entry.id.endsWith('--default-tokens')
   );
   const names = new Set();
@@ -17,7 +18,7 @@ export async function checkNativeStories(page, base) {
     sliderdots: 'slider-dots',
   };
   for (const story of stories) {
-    const name = story.title.split('/')[1].toLowerCase();
+    const name = story.title.split('/')[2].toLowerCase();
     names.add(name);
     await page.goto(`${base}/web-components/iframe.html?id=${story.id}&viewMode=story`);
     const tag = `gd-${tags[name] ?? name}`;
@@ -105,7 +106,7 @@ export async function checkNativeStories(page, base) {
         }),
       detail
     );
-  await open('layout-structure-chatcontainer--interactive-demo');
+  await open('components-layout-structure-chatcontainer--interactive-demo');
   const chatContainer = page.locator('gd-chat-container');
   await page.waitForFunction(() => document.querySelector('gd-chat-container')?.isOpen === true);
   await chatContainer.evaluate((element) => element.close());
@@ -120,7 +121,7 @@ export async function checkNativeStories(page, base) {
       })
   );
   assert.deepEqual(await toggleEvent, { open: false });
-  await open('layout-structure-column--default');
+  await open('components-layout-structure-column--default');
   assert.equal(
     await page
       .locator('gd-column')
@@ -128,16 +129,16 @@ export async function checkNativeStories(page, base) {
       .evaluate((element) => getComputedStyle(element.shadowRoot.querySelector('[part="root"]')).flexDirection),
     'column'
   );
-  await open('layout-structure-row--default');
+  await open('components-layout-structure-row--default');
   assert.equal(await page.locator('gd-row').evaluate((element) => element.getAttribute('display')), 'inline-flex');
-  await open('layout-structure-flexcontainer--default');
+  await open('components-layout-structure-flexcontainer--default');
   assert.equal(
     await page
       .locator('gd-flex-container')
       .evaluate((element) => getComputedStyle(element.shadowRoot.querySelector('[part="root"]')).display),
     'flex'
   );
-  await open('layout-structure-portal--rendering-in-target');
+  await open('components-layout-structure-portal--rendering-in-target');
   await page.getByText('Show Portal', { exact: true }).click();
   assert.equal(
     await page
@@ -147,7 +148,7 @@ export async function checkNativeStories(page, base) {
     1
   );
   assert.equal(await page.locator('gd-portal').evaluate((element) => element.portalRoot), null);
-  await open('layout-structure-portal--with-wrapper-as-tag-main');
+  await open('components-layout-structure-portal--with-wrapper-as-tag-main');
   await page.getByText('Show Portal', { exact: true }).click();
   assert.equal(await page.locator('gd-portal').evaluate((element) => element.portalRoot?.tagName), 'MAIN');
   assert.deepEqual(
@@ -159,7 +160,7 @@ export async function checkNativeStories(page, base) {
   );
   await page.getByText('Hide', { exact: true }).click();
   assert.equal(await page.locator('gd-portal').count(), 0);
-  await open('layout-structure-scroll--interactive-example');
+  await open('components-layout-structure-scroll--interactive-example');
   const scroll = page.locator('gd-scroll');
   await page.waitForFunction(() => {
     const element = document.querySelector('gd-scroll');
@@ -226,7 +227,7 @@ export async function checkNativeStories(page, base) {
   await page.mouse.move(trackBox.x + trackBox.width / 2, trackBox.y + trackBox.height - 2);
   await page.mouse.up();
   await page.waitForFunction(() => document.querySelector('gd-scroll').scrollTop > 100);
-  await open('layout-structure-scroll--vertical-scroll-only');
+  await open('components-layout-structure-scroll--vertical-scroll-only');
   await page.waitForFunction(() => document.querySelector('gd-scroll')?.scrollHeight > 198);
   assert.deepEqual(
     await page.locator('gd-scroll').evaluate((element) => ({
@@ -236,7 +237,7 @@ export async function checkNativeStories(page, base) {
     })),
     { extent: [298, 500], vertical: true, horizontal: false }
   );
-  await open('layout-structure-scroll--horizontal-scroll-only');
+  await open('components-layout-structure-scroll--horizontal-scroll-only');
   await page.waitForFunction(() => document.querySelector('gd-scroll')?.scrollWidth > 298);
   assert.deepEqual(
     await page.locator('gd-scroll').evaluate((element) => ({
@@ -246,7 +247,7 @@ export async function checkNativeStories(page, base) {
     })),
     { extent: [1020, 198], vertical: false, horizontal: true }
   );
-  await open('layout-structure-scroll--auto-hide-scrollbars');
+  await open('components-layout-structure-scroll--auto-hide-scrollbars');
   await page.waitForFunction(() =>
     document.querySelector('gd-scroll')?.shadowRoot?.querySelector('[part~="vertical-scrollbar"]')
   );
@@ -268,7 +269,7 @@ export async function checkNativeStories(page, base) {
   );
   await page.waitForTimeout(1250);
   assert.equal(await autoHideScrollbar.evaluate((element) => getComputedStyle(element).opacity), '0');
-  await open('layout-structure-scroll--auto-hide-vertical-only');
+  await open('components-layout-structure-scroll--auto-hide-vertical-only');
   await page.waitForFunction(() => document.querySelector('gd-scroll')?.scrollHeight === 980);
   assert.deepEqual(
     await page.locator('gd-scroll').evaluate((element) => ({
@@ -278,10 +279,10 @@ export async function checkNativeStories(page, base) {
     })),
     { extent: [298, 980], vertical: true, horizontal: false }
   );
-  await open('atoms-button--disabled-button');
+  await open('components-atoms-button--disabled-button');
   await page.getByRole('button', { name: 'Disabled Button', exact: true }).waitFor();
   assert.ok(await page.getByRole('button', { name: 'Disabled Button', exact: true }).isDisabled());
-  await open('atoms-input--primary-default-with-label-and-helper-text');
+  await open('components-atoms-input--primary-default-with-label-and-helper-text');
   // The story's play function types "hello" after render; wait for it so it cannot overwrite the fill below.
   await page.waitForFunction(
     () => document.querySelector('gd-input')?.shadowRoot?.querySelector('input')?.value === 'hello'
@@ -289,14 +290,14 @@ export async function checkNativeStories(page, base) {
   // The wrapping <label> also contains the helper text, so the accessible name is "Label Helper text".
   await page.getByRole('textbox', { name: /^Label/ }).fill('Updated value');
   await event({ value: 'Updated value' });
-  await open('atoms-input--read-only');
+  await open('components-atoms-input--read-only');
   assert.ok(
     await page
       .getByRole('textbox')
       .isEditable()
       .then((value) => !value)
   );
-  await open('atoms-checkbox--default');
+  await open('components-atoms-checkbox--default');
   // The native input is visually hidden; users activate its visible label.
   // The story's play function leaves the checkbox checked, so the first click unchecks it.
   await page.locator('gd-checkbox label').click();
@@ -308,12 +309,12 @@ export async function checkNativeStories(page, base) {
     await page.waitForFunction(() => document.querySelector('gd-select')?.shadowRoot?.querySelector('.trigger'));
     await openSelect();
   };
-  await open('atoms-select--default');
+  await open('components-atoms-select--default');
   await openSelect();
   await page.getByRole('option', { name: 'Option 3' }).click();
   await event({ value: { name: 'Option 3', value: 'option3' } });
   await page.getByRole('listbox').waitFor({ state: 'hidden' });
-  await open('atoms-select--multiple-select');
+  await open('components-atoms-select--multiple-select');
   await openSelect();
   await page.getByRole('option', { name: /Option 3/ }).click();
   await event({
@@ -323,12 +324,12 @@ export async function checkNativeStories(page, base) {
     ],
   });
   await page.getByRole('listbox').waitFor();
-  await open('atoms-select--searchable');
+  await open('components-atoms-select--searchable');
   await openSelect();
   await page.getByRole('textbox', { name: 'Search fruits...' }).fill('ban');
   await page.getByRole('option', { name: 'Banana' }).waitFor();
   assert.equal(await page.getByRole('option', { name: 'Apple' }).count(), 0);
-  await open('atoms-typography--heading');
+  await open('components-atoms-typography--heading');
   assert.equal(await page.locator('gd-typography').count(), 18);
   assert.deepEqual(
     await page
@@ -357,42 +358,42 @@ export async function checkNativeStories(page, base) {
       'sub',
     ]
   );
-  await open('atoms-typography--display');
+  await open('components-atoms-typography--display');
   const displayFontSizes = await page
     .locator('gd-typography')
     .evaluateAll((elements) =>
       elements.map((element) => getComputedStyle(element.shadowRoot.firstElementChild).fontSize)
     );
   assert.equal(new Set(displayFontSizes).size, 5);
-  await open('atoms-slider--default');
+  await open('components-atoms-slider--default');
   const slider = page.getByRole('slider', { name: 'Slider' });
   await slider.fill('55');
   await event({ value: 55 });
-  await open('atoms-sliderdots--default');
+  await open('components-atoms-sliderdots--default');
   await page.getByRole('tab', { name: 'Go to slide 3' }).click();
   await event({ index: 2 });
-  await open('atoms-switch--default');
+  await open('components-atoms-switch--default');
   await page.locator('gd-switch label').click();
   await event({ checked: true });
-  await open('atoms-textarea--default');
+  await open('components-atoms-textarea--default');
   await page.getByRole('textbox').fill('Updated comment');
   await event({ value: 'Updated comment' });
-  await open('atoms-toggle--default');
+  await open('components-atoms-toggle--default');
   await page.getByRole('button', { name: 'Option 2', exact: true }).click();
   await event({ value: 'Option 2' });
-  await open('atoms-truncate--line-truncation');
+  await open('components-atoms-truncate--line-truncation');
   assert.equal(
     await page
       .locator('gd-truncate')
       .evaluate((element) => getComputedStyle(element.shadowRoot.querySelector('[part="content"]')).webkitLineClamp),
     '2'
   );
-  await open('atoms-wrapper--custom-tag-wrapper');
+  await open('components-atoms-wrapper--custom-tag-wrapper');
   assert.equal(
     await page.locator('gd-wrapper').evaluate((element) => element.shadowRoot.firstElementChild.tagName),
     'SECTION'
   );
-  await open('molecules-counter--default');
+  await open('components-molecules-counter--default');
   await page.getByRole('button', { name: 'Increment counter', exact: true }).click();
   await event({ value: 2 });
   await page.getByRole('button', { name: 'Decrement counter', exact: true }).click();
@@ -414,7 +415,7 @@ export async function checkNativeStories(page, base) {
         getComputedStyle(content).display === 'none'
       );
     });
-  await open('molecules-menu--default');
+  await open('components-molecules-menu--default');
   await page.getByRole('button', { name: 'Actions', exact: true }).click();
   await page.getByRole('button', { name: 'Edit', exact: true }).click();
   await event({ data: { name: 'Edit', value: 'edit' }, value: 'edit' });
@@ -427,7 +428,7 @@ export async function checkNativeStories(page, base) {
   await page.getByRole('button', { name: 'Edit', exact: true }).waitFor();
   await page.getByRole('button', { name: 'Outside menu' }).click();
   await menuClosed();
-  await open('molecules-menu--close-on-select-false');
+  await open('components-molecules-menu--close-on-select-false');
   await page.getByRole('button', { name: 'Actions', exact: true }).click();
   await page.getByRole('button', { name: 'Archive', exact: true }).click();
   await event({ data: { name: 'Archive', value: 'archive' }, value: 'archive' });
diff --git a/bin/storybook/routes.d.mts b/bin/storybook/routes.d.mts
index f0b8cf5..cdbc686 100644
--- a/bin/storybook/routes.d.mts
+++ b/bin/storybook/routes.d.mts
@@ -4,3 +4,6 @@ export const sharedDocIds: string[];
 export const storybookOrigin: string;
 export function legacyRedirect(href: string, ids: string[], sharedIds?: string[]): string | null;
 export function legacyRedirectHead(): string;
+export function migratedReactId(id: string): string;
+export function webComponentsRedirect(href: string): string | null;
+export function webComponentsRedirectHead(): string;
diff --git a/bin/storybook/routes.mjs b/bin/storybook/routes.mjs
index eb501cd..faf6b51 100644
--- a/bin/storybook/routes.mjs
+++ b/bin/storybook/routes.mjs
@@ -8,15 +8,26 @@ export const sharedDocs = JSON.parse(readFileSync(new URL('./shared-docs.json',
 export const sharedDocIds = Object.values(sharedDocs);
 export const storybookOrigin = 'https://storybook.cto-rnd-system-design.griddynamics.net';
 
+/** Canonical React ID for a frozen legacy ID (tier groups live under Components). */
+export function migratedReactId(id) {
+  return `react-${id}`.replace(
+    /^react-(atoms|molecules|organisms|layout-structure|templates)-/,
+    'react-components-$1-'
+  );
+}
+
 /** Resolve legacy manager, iframe and bare /docs links without dropping URL state. */
 export function legacyRedirect(href, ids, sharedIds = []) {
   const url = new URL(href);
   const known = new Set(ids);
   const shared = new Set(sharedIds);
+  // Atomic tiers moved under a Components parent: atoms-button -> components-atoms-button.
+  const tiers = '(atoms|molecules|organisms|layout-structure|templates)';
+  const nest = (id) => id.replace(new RegExp(`^(react-|web-components_)?${tiers}-`), '$1components-$2-');
   const upgrade = (id) => {
     if (shared.has(id)) return id;
     if (id.startsWith('react-') && shared.has(id.slice(6))) return id.slice(6);
-    return known.has(id) ? `react-${id}` : id;
+    return known.has(id) ? nest(`react-${id}`) : nest(id);
   };
   const original = url.href;
   const path = url.searchParams.get('path');
@@ -46,3 +57,28 @@ export function legacyRedirect(href, ids, sharedIds = []) {
 export function legacyRedirectHead() {
   return `<script>var migratedStorybookUrl = (${legacyRedirect.toString()})(location.href, ${JSON.stringify(legacyReactIds)}, ${JSON.stringify(sharedDocIds)}); if (migratedStorybookUrl) location.replace(migratedStorybookUrl);</script>`;
 }
+
+/** Redirect pre-Components Web Components URLs opened directly on the child Storybook. */
+export function webComponentsRedirect(href) {
+  const url = new URL(href);
+  const upgrade = (id) => id.replace(/^(atoms|molecules|layout-structure)-/, 'components-$1-');
+  const original = url.href;
+  const path = url.searchParams.get('path');
+  if (path) {
+    url.searchParams.set(
+      'path',
+      path.replace(/^(\/(?:docs|story)\/)([^#?]+)/, (_, prefix, id) => prefix + upgrade(id))
+    );
+  }
+  const id = url.searchParams.get('id');
+  if (id) url.searchParams.set('id', upgrade(id));
+  const before = new URL(original);
+  return url.searchParams.get('path') !== before.searchParams.get('path') ||
+    url.searchParams.get('id') !== before.searchParams.get('id')
+    ? url.href
+    : null;
+}
+
+export function webComponentsRedirectHead() {
+  return `<script>var migratedWebComponentsUrl = (${webComponentsRedirect.toString()})(location.href); if (migratedWebComponentsUrl) location.replace(migratedWebComponentsUrl);</script>`;
+}
diff --git a/bin/storybook/routes.test.mjs b/bin/storybook/routes.test.mjs
index 8213365..b33c94c 100644
--- a/bin/storybook/routes.test.mjs
+++ b/bin/storybook/routes.test.mjs
@@ -1,6 +1,14 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
-import { legacyReactIds, sharedDocIds, legacyRedirect, legacyRedirectHead } from './routes.mjs';
+import {
+  legacyReactIds,
+  sharedDocIds,
+  legacyRedirect,
+  legacyRedirectHead,
+  migratedReactId,
+  webComponentsRedirect,
+  webComponentsRedirectHead,
+} from './routes.mjs';
 
 const origin = 'https://storybook.example';
 
@@ -9,7 +17,7 @@ test('every legacy story and docs route resolves to its canonical root', () => {
     const kind = id.endsWith('--docs') ? 'docs' : 'story';
     const href = `${origin}/?path=/${kind}/${id}&args=size:sm&globals=theme:dark#example`;
     const result = new URL(legacyRedirect(href, legacyReactIds, sharedDocIds) || href);
-    assert.equal(result.searchParams.get('path'), `/${kind}/${sharedDocIds.includes(id) ? id : `react-${id}`}`);
+    assert.equal(result.searchParams.get('path'), `/${kind}/${sharedDocIds.includes(id) ? id : migratedReactId(id)}`);
     assert.equal(result.searchParams.get('args'), 'size:sm');
     assert.equal(result.searchParams.get('globals'), 'theme:dark');
     assert.equal(result.hash, '#example');
@@ -21,7 +29,7 @@ test('iframe links retain their view mode and args', () => {
     legacyRedirect(`${origin}/iframe.html?id=atoms-button--docs&viewMode=docs&args=size:sm`, legacyReactIds)
   );
   assert.equal(result.pathname, '/iframe.html');
-  assert.equal(result.searchParams.get('id'), 'react-atoms-button--docs');
+  assert.equal(result.searchParams.get('id'), 'react-components-atoms-button--docs');
   assert.equal(result.searchParams.get('viewMode'), 'docs');
   assert.equal(result.searchParams.get('args'), 'size:sm');
 });
@@ -40,6 +48,8 @@ test('canonical, composed, unrelated and unknown routes are not redirected', ()
     '/?path=/docs/introduction-welcome--docs',
     '/?path=/docs/react-introduction-getting-started--docs',
     '/?path=/story/web-components_introduction-overview--overview',
+    '/?path=/docs/react-components-atoms-button--docs',
+    '/?path=/docs/web-components_components-atoms-button--docs',
     '/web-components/?path=/story/introduction-overview--overview',
     '/?path=/docs/unknown--docs',
     '/docs/api',
@@ -83,5 +93,66 @@ test('early head script is self-contained', () => {
     href: `${origin}/?path=/docs/atoms-button--docs`,
     replace: (url) => calls.push(url),
   });
-  assert.equal(new URL(calls[0]).searchParams.get('path'), '/docs/react-atoms-button--docs');
+  assert.equal(new URL(calls[0]).searchParams.get('path'), '/docs/react-components-atoms-button--docs');
+});
+
+test('interim React and Web Components tier links move under Components', () => {
+  for (const [from, to] of [
+    ['react-atoms-button--docs', 'react-components-atoms-button--docs'],
+    ['react-layout-structure-row--default', 'react-components-layout-structure-row--default'],
+    ['web-components_atoms-button--docs', 'web-components_components-atoms-button--docs'],
+    ['web-components_molecules-counter--default', 'web-components_components-molecules-counter--default'],
+  ]) {
+    const kind = from.endsWith('--docs') ? 'docs' : 'story';
+    const result = new URL(legacyRedirect(`${origin}/?path=/${kind}/${from}`, legacyReactIds, sharedDocIds));
+    assert.equal(result.searchParams.get('path'), `/${kind}/${to}`);
+  }
+});
+
+test('direct Web Components child links move under Components', () => {
+  const base = `${origin}/web-components`;
+  for (const [href, key, expected] of [
+    [
+      `${base}/?path=/story/atoms-button--default&args=variant:secondary`,
+      'path',
+      '/story/components-atoms-button--default',
+    ],
+    [`${base}/?path=/docs/molecules-counter--docs`, 'path', '/docs/components-molecules-counter--docs'],
+    [
+      `${base}/iframe.html?id=layout-structure-row--default&viewMode=story`,
+      'id',
+      'components-layout-structure-row--default',
+    ],
+  ])
+    assert.equal(new URL(webComponentsRedirect(href)).searchParams.get(key), expected);
+  assert.equal(
+    new URL(
+      webComponentsRedirect(`${base}/?path=/story/atoms-button--default&args=variant:secondary`)
+    ).searchParams.get('args'),
+    'variant:secondary'
+  );
+  for (const path of [
+    '/?path=/story/components-atoms-button--default',
+    '/?path=/story/introduction-overview--overview',
+    '/iframe.html?id=introduction-overview--overview',
+    '/',
+  ])
+    assert.equal(webComponentsRedirect(base + path), null);
+});
+
+test('Web Components early head script is self-contained', () => {
+  const calls = [];
+  const script = webComponentsRedirectHead().replace(/^<script>|<\/script>$/g, '');
+  new Function('location', script)({
+    href: `${origin}/web-components/iframe.html?id=atoms-button--default`,
+    replace: (url) => calls.push(url),
+  });
+  assert.equal(new URL(calls[0]).searchParams.get('id'), 'components-atoms-button--default');
+});
+
+test('iframe links with legacy and interim tier IDs resolve to the Components IDs', () => {
+  for (const id of ['atoms-button--default', 'react-atoms-button--default']) {
+    const result = new URL(legacyRedirect(`${origin}/iframe.html?id=${id}&viewMode=story`, ['atoms-button--default']));
+    assert.equal(result.searchParams.get('id'), 'react-components-atoms-button--default');
+  }
 });
diff --git a/bin/storybook/smoke-test.mjs b/bin/storybook/smoke-test.mjs
index 6cc6aca..024404c 100644
--- a/bin/storybook/smoke-test.mjs
+++ b/bin/storybook/smoke-test.mjs
@@ -100,7 +100,7 @@ try {
   const nativeFrame = page.frameLocator('#storybook-ref-web-components');
   await nativeFrame.getByRole('heading', { name: 'Using Web Components', exact: true }).waitFor();
 
-  await page.goto(`${base}/?path=/story/web-components_atoms-button--default&panel=addon-controls`);
+  await page.goto(`${base}/?path=/story/web-components_components-atoms-button--default&panel=addon-controls`);
   await nativeFrame.getByRole('button', { name: 'Button', exact: true }).waitFor();
   await page.getByText('variant', { exact: true }).first().waitFor();
   await page.getByRole('combobox', { name: 'variant', exact: true }).selectOption('secondary');
@@ -110,11 +110,11 @@ try {
       'secondary'
   );
   assert.equal(await nativeFrame.locator('gd-button').evaluate((element) => element.variant), 'secondary');
-  await page.goto(`${base}/?path=/docs/web-components_atoms-button--docs`);
+  await page.goto(`${base}/?path=/docs/web-components_components-atoms-button--docs`);
   await nativeFrame.getByRole('heading', { name: 'Button', exact: true }).first().waitFor();
 
   await page.goto(`${base}/iframe.html?id=atoms-button--default&viewMode=story&args=size:sm`);
-  await page.waitForURL((url) => url.searchParams.get('id') === 'react-atoms-button--default');
+  await page.waitForURL((url) => url.searchParams.get('id') === 'react-components-atoms-button--default');
   await page.getByRole('button').first().waitFor();
   assert.equal(new URL(page.url()).searchParams.get('args'), 'size:sm');
   if (!process.argv.includes('--url')) await checkNativeStories(page, base);
diff --git a/bin/storybook/story-parity.mjs b/bin/storybook/story-parity.mjs
index fc23145..27d1c94 100644
--- a/bin/storybook/story-parity.mjs
+++ b/bin/storybook/story-parity.mjs
@@ -111,7 +111,7 @@ export async function checkRenderedStoryParity(browser, reactBase, webBase, filt
     for (const target of Object.values(webIndex.entries).filter(
       (entry) =>
         entry.type === 'story' &&
-        /^(Atoms|Molecules)\//.test(entry.title) &&
+        /^Components\/(Atoms|Molecules)\//.test(entry.title) &&
         !entry.id.endsWith('--default-tokens') &&
         (!filter || entryMatches(entry, filter))
     )) {
@@ -156,12 +156,12 @@ export async function checkRenderedStoryParity(browser, reactBase, webBase, filt
         // Text equality cannot catch a checkbox rendered with text-field chrome.
         // Measure the painted controls, not the deliberately hidden Checkbox input.
         if (
-          /^atoms-input--(checkbox-with-label|radio.*with-label|primary-default-with-label-and-helper-text)$/.test(
+          /^components-atoms-input--(checkbox-with-label|radio.*with-label|primary-default-with-label-and-helper-text)$/.test(
             target.id
           ) ||
-          /^atoms-checkbox--(default|disabled|sizes|indeterminate)$/.test(target.id)
+          /^components-atoms-checkbox--(default|disabled|sizes|indeterminate)$/.test(target.id)
         ) {
-          const isCheckbox = target.id.startsWith('atoms-checkbox--');
+          const isCheckbox = target.id.startsWith('components-atoms-checkbox--');
           const geometry = await Promise.all(
             pages.map((page, index) =>
               page
diff --git a/libs/ui/.storybook/main.ts b/libs/ui/.storybook/main.ts
index 8d82297..d913f69 100644
--- a/libs/ui/.storybook/main.ts
+++ b/libs/ui/.storybook/main.ts
@@ -6,6 +6,7 @@ import remarkGfm from 'remark-gfm';
 import { legacyRedirectHead, sharedDocs } from '../../../bin/storybook/routes.mjs';
 
 const sharedNames = Object.keys(sharedDocs).join('|');
+const tiers = '@(atoms|molecules|organisms|layout|widget)';
 const catalogHeadingStyles = `<style>
   #react > button[data-action='collapse-root'] {
     color: #2e3338;
@@ -15,13 +16,25 @@ const catalogHeadingStyles = `<style>
     letter-spacing: normal;
     text-transform: none;
   }
+  /* React sub-sections (Atoms, Molecules, ...) match the Web Components section titles. */
+  .sidebar-item[data-parent-id='react'][data-nodetype='group'] > button {
+    color: #5c6570;
+    font-size: 11px;
+    font-weight: 700;
+    line-height: 16px;
+    letter-spacing: 1.76px;
+    text-transform: uppercase;
+  }
 </style>`;
 
 const config: StorybookConfig = {
   stories: [
     { directory: '../src', files: `**/@(${sharedNames}).mdx` },
-    { directory: '../src', files: `**/!(${sharedNames}).mdx`, titlePrefix: 'React' },
-    { directory: '../src', files: '**/*.stories.@(js|jsx|mjs|ts|tsx)', titlePrefix: 'React' },
+    // Atomic tiers (Atoms, Molecules, Organisms, Layout & Structure, Templates) nest under React/Components.
+    { directory: '../src/components', files: `${tiers}/**/*.mdx`, titlePrefix: 'React/Components' },
+    { directory: '../src/components', files: `${tiers}/**/*.stories.@(js|jsx|mjs|ts|tsx)`, titlePrefix: 'React/Components' },
+    { directory: '../src', files: `!(components)/**/!(${sharedNames}).mdx`, titlePrefix: 'React' },
+    { directory: '../src', files: '!(components)/**/*.stories.@(js|jsx|mjs|ts|tsx)', titlePrefix: 'React' },
   ],
   refs: (_config, { configType }) => ({
     'web-components': {
diff --git a/libs/ui/.storybook/preview.ts b/libs/ui/.storybook/preview.ts
index adabe8b..453904c 100644
--- a/libs/ui/.storybook/preview.ts
+++ b/libs/ui/.storybook/preview.ts
@@ -42,11 +42,8 @@ const preview: Preview = {
             'Support & Questions',
             'Form Configurator',
             ['Getting Started', 'Data Schema', 'Controls', 'UI Schema & Layouts', 'Logger', 'Custom Controls', '*'],
-            'Atoms',
-            'Molecules',
-            'Organisms',
-            'Layout & Structure',
-            'Templates',
+            'Components',
+            ['Atoms', 'Molecules', 'Organisms', 'Layout & Structure', 'Templates'],
             'Patterns & Best Practices',
             ['AI Experience', 'Prompt Engineering & AI Integration', '*'],
             'Domain Solutions',
diff --git a/libs/ui/llms.txt b/libs/ui/llms.txt
index 0183197..5214d21 100644
--- a/libs/ui/llms.txt
+++ b/libs/ui/llms.txt
@@ -84,7 +84,7 @@ Pre-built indexes for quick discovery:
 > Run `yarn build:ui` to regenerate. Do not edit the block between the markers manually.
 
 <!-- AUTO-GENERATED:COMPONENTS:START -->
-66 components total — generated from libs/ui/src/ai/schemas/ on 2026-10-19.
+66 components total — generated from libs/ui/src/ai/schemas/ on 2026-10-20.
 
 ## Other
 
diff --git a/libs/ui/src/ai/README.md b/libs/ui/src/ai/README.md
index c8f55c0..dd13da4 100644
--- a/libs/ui/src/ai/README.md
+++ b/libs/ui/src/ai/README.md
@@ -594,7 +594,7 @@ yarn test:ai:watch
 
 <!-- AUTO-GENERATED:COMPONENTS:START -->
 
-_66 components total — generated from `libs/ui/src/ai/schemas/` on 2026-10-19._
+_66 components total — generated from `libs/ui/src/ai/schemas/` on 2026-10-20._
 
 ### Other
 
diff --git a/libs/web-components/.storybook/main.ts b/libs/web-components/.storybook/main.ts
index e72e906..158aa88 100644
--- a/libs/web-components/.storybook/main.ts
+++ b/libs/web-components/.storybook/main.ts
@@ -1,7 +1,16 @@
 import type { StorybookConfig } from '@storybook/web-components-vite';
+// Build-time workspace tooling, not a dependency of the shipped UI library.
+// eslint-disable-next-line @nx/enforce-module-boundaries
+import { webComponentsRedirectHead } from '../../../bin/storybook/routes.mjs';
 
 const config: StorybookConfig = {
-  stories: ['../stories/**/*.stories.ts'],
+  stories: [
+    '../stories/Overview.stories.ts',
+    // Atomic tiers (Atoms, Molecules, Layout & Structure) nest under Components.
+    { directory: '../stories', files: '!(Overview).stories.ts', titlePrefix: 'Components' },
+  ],
+  managerHead: (head) => `${webComponentsRedirectHead()}${head}`,
+  previewHead: (head) => `${webComponentsRedirectHead()}${head}`,
   staticDirs: [{ from: '../../ui/src/assets', to: '/' }],
   addons: ['@storybook/addon-docs', '@storybook/addon-a11y'],
   framework: {
diff --git a/libs/web-components/.storybook/preview.ts b/libs/web-components/.storybook/preview.ts
index 4694774..e4f99f3 100644
--- a/libs/web-components/.storybook/preview.ts
+++ b/libs/web-components/.storybook/preview.ts
@@ -9,7 +9,7 @@ import { storySource } from '../stories/helpers';
 const preview: Preview = {
   parameters: {
     layout: 'padded',
-    options: { storySort: { order: ['Introduction', 'Atoms', 'Molecules'] } },
+    options: { storySort: { order: ['Introduction', 'Components', ['Atoms', 'Molecules', 'Layout & Structure']] } },
     a11y: { test: 'todo' },
     docs: {
       source: {
diff --git a/libs/web-components/README.md b/libs/web-components/README.md
index 01cde4b..ae26aed 100644
--- a/libs/web-components/README.md
+++ b/libs/web-components/README.md
@@ -127,39 +127,39 @@ The shared Storybook is started from the repository root with `npm run storybook
 opened at `http://localhost:6006`. Its **Web Components** section contains native stories, Controls, and docs for all twenty-five
 existing atoms and molecules plus the separately exported Column, FlexContainer, Portal, Row, and Scroll components. Interactive stories show native event payloads below the component.
 
-| Storybook component                                                                                                         | React-contract coverage                                                                              |
-| --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
-| [Avatar](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_atoms-avatar--docs)            | Image, fallback, badge, every size, custom colors                                                    |
-| [Badge](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_atoms-badge--docs)              | Variants, appearances, sizes, disabled state, and icon slots                                         |
-| [Box](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_atoms-box--docs)                  | Vertical/horizontal layout, borders, highlight, shadow hover, and slotted content                    |
-| [Button](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_atoms-button--docs)            | Every variant and radius, full-width, icon-only, loading, disabled, icon slots                       |
-| [Checkbox](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_atoms-checkbox--docs)        | Checked, indeterminate, disabled, both sizes; `gd-change` → `{ checked }`                            |
-| [Input](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_atoms-input--docs)              | Types, validation colors, read-only/disabled, adornments; `gd-input`/`gd-change`                     |
-| [Image](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_atoms-image--docs)              | Loading placeholder, fallback slot, caption, sizing, object fit, and load/error events               |
-| [Icon](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_atoms-icon--docs)                | All built-in icons from the shared core catalog, token sizes, and theme-aware fills                  |
-| [InputFile](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_atoms-inputfile--docs)      | Accept/capture/multiple/disabled behavior, custom label, icon label, and `gd-change` file detail     |
-| [Label](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_atoms-label--docs)              | Native label association, slotted content, icons, and style overrides                                |
-| [Link component](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_atoms-link--docs)      | Variants, sizes, underline states, disabled semantics, targets, and href                             |
-| [Loader](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_atoms-loader--docs)            | Circle/dots, sizes, rounded dots, wrappers, section, and native full-page top layer                  |
-| [Select](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_atoms-select--docs)            | Single/multiple, search, auto-open, colors, adornments, custom initiator; `gd-change`                |
-| [Separator](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_atoms-separator--docs)      | Orientations, line variants, thickness, labels, semantic elements, lengths, and colors               |
-| [Skeleton](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_atoms-skeleton--docs)        | Rounded/rectangular/circular shapes, dimensions, colors, animation control, and child content        |
-| [Slider](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_atoms-slider--docs)            | Range limits, controlled values, keyboard input, disabled state, visual fill, and events             |
-| [SliderDots](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_atoms-sliderdots--docs)    | Accessible carousel tabs, active state, larger sets, and selection events                            |
-| [Switch](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_atoms-switch--docs)            | Checked, disabled, loading, controlled/uncontrolled behavior, label placement, and events            |
-| [Textarea](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_atoms-textarea--docs)        | Values, colors, resize modes, dynamic height, focus, character limits, and input/change events       |
-| [Toggle](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_atoms-toggle--docs)            | String/object items, selected value, disabled state, custom item rendering, and change events        |
-| [Truncate](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_atoms-truncate--docs)        | Single/multiple-line truncation, style overrides, overflow measurement, and accessibility            |
-| [Typography](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_atoms-typography--docs)    | All 18 variants, display sizes, style variants, alignment/color controls, semantic override          |
-| [Wrapper](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_atoms-wrapper--docs)          | Inline, section and full-page layout variants, semantic tag override, content, and styles            |
-| [Counter](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_molecules-counter--docs)      | Minimum/maximum, custom range, disabled; `gd-change` → `{ value: number }`                           |
-| [Menu](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_molecules-menu--docs)            | Placement, offsets, height constraints, close/persist behavior; `gd-change` → `{ data, value }`      |
-| ChatContainer                                                                                                               | Responsive named-slot layout, collapsed rail, `gd-toggle-sidebar`, and imperative state methods      |
-| Column                                                                                                                      | `gd-column`; native flex-element and Box style surface, styles, and slotted children                 |
-| FlexContainer                                                                                                               | `gd-flex-container`; complete Box prop surface, styles, classes, and slotted children                |
-| Portal                                                                                                                      | `gd-portal`; target placement, wrapper variants/tags, styles, cleanup, and scroll blocking           |
-| Row                                                                                                                         | `gd-row`; native flex-element and Box style surface, styles, and slotted children                    |
-| [Scroll](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_layout-structure-scroll--docs) | Vertical/horizontal modes, automatic overflow, auto-hide, draggable thumbs, and imperative scrolling |
+| Storybook component                                                                                                                    | React-contract coverage                                                                              |
+| -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| [Avatar](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_components-atoms-avatar--docs)            | Image, fallback, badge, every size, custom colors                                                    |
+| [Badge](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_components-atoms-badge--docs)              | Variants, appearances, sizes, disabled state, and icon slots                                         |
+| [Box](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_components-atoms-box--docs)                  | Vertical/horizontal layout, borders, highlight, shadow hover, and slotted content                    |
+| [Button](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_components-atoms-button--docs)            | Every variant and radius, full-width, icon-only, loading, disabled, icon slots                       |
+| [Checkbox](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_components-atoms-checkbox--docs)        | Checked, indeterminate, disabled, both sizes; `gd-change` → `{ checked }`                            |
+| [Input](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_components-atoms-input--docs)              | Types, validation colors, read-only/disabled, adornments; `gd-input`/`gd-change`                     |
+| [Image](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_components-atoms-image--docs)              | Loading placeholder, fallback slot, caption, sizing, object fit, and load/error events               |
+| [Icon](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_components-atoms-icon--docs)                | All built-in icons from the shared core catalog, token sizes, and theme-aware fills                  |
+| [InputFile](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_components-atoms-inputfile--docs)      | Accept/capture/multiple/disabled behavior, custom label, icon label, and `gd-change` file detail     |
+| [Label](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_components-atoms-label--docs)              | Native label association, slotted content, icons, and style overrides                                |
+| [Link component](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_components-atoms-link--docs)      | Variants, sizes, underline states, disabled semantics, targets, and href                             |
+| [Loader](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_components-atoms-loader--docs)            | Circle/dots, sizes, rounded dots, wrappers, section, and native full-page top layer                  |
+| [Select](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_components-atoms-select--docs)            | Single/multiple, search, auto-open, colors, adornments, custom initiator; `gd-change`                |
+| [Separator](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_components-atoms-separator--docs)      | Orientations, line variants, thickness, labels, semantic elements, lengths, and colors               |
+| [Skeleton](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_components-atoms-skeleton--docs)        | Rounded/rectangular/circular shapes, dimensions, colors, animation control, and child content        |
+| [Slider](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_components-atoms-slider--docs)            | Range limits, controlled values, keyboard input, disabled state, visual fill, and events             |
+| [SliderDots](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_components-atoms-sliderdots--docs)    | Accessible carousel tabs, active state, larger sets, and selection events                            |
+| [Switch](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_components-atoms-switch--docs)            | Checked, disabled, loading, controlled/uncontrolled behavior, label placement, and events            |
+| [Textarea](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_components-atoms-textarea--docs)        | Values, colors, resize modes, dynamic height, focus, character limits, and input/change events       |
+| [Toggle](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_components-atoms-toggle--docs)            | String/object items, selected value, disabled state, custom item rendering, and change events        |
+| [Truncate](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_components-atoms-truncate--docs)        | Single/multiple-line truncation, style overrides, overflow measurement, and accessibility            |
+| [Typography](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_components-atoms-typography--docs)    | All 18 variants, display sizes, style variants, alignment/color controls, semantic override          |
+| [Wrapper](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_components-atoms-wrapper--docs)          | Inline, section and full-page layout variants, semantic tag override, content, and styles            |
+| [Counter](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_components-molecules-counter--docs)      | Minimum/maximum, custom range, disabled; `gd-change` → `{ value: number }`                           |
+| [Menu](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_components-molecules-menu--docs)            | Placement, offsets, height constraints, close/persist behavior; `gd-change` → `{ data, value }`      |
+| ChatContainer                                                                                                                          | Responsive named-slot layout, collapsed rail, `gd-toggle-sidebar`, and imperative state methods      |
+| Column                                                                                                                                 | `gd-column`; native flex-element and Box style surface, styles, and slotted children                 |
+| FlexContainer                                                                                                                          | `gd-flex-container`; complete Box prop surface, styles, classes, and slotted children                |
+| Portal                                                                                                                                 | `gd-portal`; target placement, wrapper variants/tags, styles, cleanup, and scroll blocking           |
+| Row                                                                                                                                    | `gd-row`; native flex-element and Box style surface, styles, and slotted children                    |
+| [Scroll](https://storybook.cto-rnd-system-design.griddynamics.net/?path=/docs/web-components_components-layout-structure-scroll--docs) | Vertical/horizontal modes, automatic overflow, auto-hide, draggable thumbs, and imperative scrolling |
 
 ### Layout components
 

From 8b72134cc1d0076acbe816b63733605cd9233d7e Mon Sep 17 00:00:00 2001
From: Zlodej43sm <8863227+Zlodej43sm@users.noreply.github.com>
Date: Tue, 20 Oct 2026 16:08:56 +0200
Subject: [PATCH 2/3] refactor: bundle GridKit tokens and icons into standalone
 web-components package

Make `web-components` fully standalone by bundling `gd-design-library/tokens` and `/icons` instead of externalizing them. Consumers now install only `web-components` and import `defaultTheme` directly from it. Update README, package.json, Vite config, and stories to remove `gd-design-library` install instructions and import examples. Move `gd-design-library` to devDependencies.
---
 libs/web-components/README.md                 | 13 ++---
 libs/web-components/package.json              |  4 +-
 libs/web-components/src/index.ts              |  3 +
 .../stories/Overview.stories.ts               | 13 ++---
 libs/web-components/vite.config.ts            | 55 ++++++++-----------
 package-lock.json                             |  2 +
 package.json                                  |  2 +
 7 files changed, 45 insertions(+), 47 deletions(-)

diff --git a/libs/web-components/README.md b/libs/web-components/README.md
index ae26aed..aefde54 100644
--- a/libs/web-components/README.md
+++ b/libs/web-components/README.md
@@ -7,14 +7,13 @@ Available elements: `gd-avatar`, `gd-badge`, `gd-box`, `gd-button`, `gd-checkbox
 ## Install
 
 ```bash
-npm install web-components gd-design-library
+npm install web-components
 ```
 
-Import the library once to register its custom elements. Each element needs a GridKit theme; assign it as a JavaScript property, not as an HTML attribute.
+`web-components` is standalone: the GridKit design tokens and icons are bundled in, so you do not install `gd-design-library`. Import the package once to register its custom elements. Each element needs a GridKit theme; assign it as a JavaScript property, not as an HTML attribute.
 
 ```ts
-import 'web-components';
-import { defaultTheme } from 'gd-design-library/tokens';
+import { defaultTheme } from 'web-components'; // also registers every gd-* custom element
 
 document.querySelectorAll<HTMLElement & { theme: unknown }>('gd-button, gd-checkbox, gd-input').forEach((element) => {
   element.theme = defaultTheme;
@@ -36,7 +35,7 @@ Use attributes for strings and booleans, such as `variant`, `label`, and `disabl
 
 `<gd-theme-provider>` is the counterpart of React's `ThemeProvider` + `useTheme()`. Every `gd-*` element
 below it — including inside other elements' shadow roots — uses its theme and re-renders when it changes.
-Tokens come from the same `gd-design-library/tokens` as React, so one theme object drives both.
+The bundled tokens are the same ones `gd-design-library` ships for React, so one theme object shape drives both.
 
 ```html
 <gd-theme-provider is-default>
@@ -67,7 +66,7 @@ import 'web-components';
 
 // app.component.ts
 import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
-import { defaultTheme } from 'gd-design-library/tokens';
+import { defaultTheme } from 'web-components';
 
 @Component({
   selector: 'app-root',
@@ -106,7 +105,7 @@ createApp(App).mount('#app');
 ```vue
 <script setup lang="ts">
 import { ref } from 'vue';
-import { defaultTheme } from 'gd-design-library/tokens';
+import { defaultTheme } from 'web-components';
 
 const email = ref('');
 const accepted = ref(false);
diff --git a/libs/web-components/package.json b/libs/web-components/package.json
index f117b85..6832e7c 100644
--- a/libs/web-components/package.json
+++ b/libs/web-components/package.json
@@ -2,16 +2,16 @@
   "name": "web-components",
   "version": "0.0.0",
   "private": true,
-  "description": "Lit web-components implementation of gd-design-library's atoms, built on the same gd-design-library tokens as the React components.",
+  "description": "Standalone Lit web-components implementation of gd-design-library's atoms. The GridKit design tokens and icons are bundled in, so consumers install only this package.",
   "type": "module",
   "main": "./index.js",
   "types": "./index.d.ts",
   "dependencies": {
-    "gd-design-library": "*",
     "lit": "^3.2.1",
     "zustand": "^5.0.6"
   },
   "devDependencies": {
+    "gd-design-library": "*",
     "@lit-labs/ssr": "^4.1.0"
   }
 }
diff --git a/libs/web-components/src/index.ts b/libs/web-components/src/index.ts
index a8353c1..093ca02 100644
--- a/libs/web-components/src/index.ts
+++ b/libs/web-components/src/index.ts
@@ -36,3 +36,6 @@ export { GdScroll, type ScrollbarVisibility } from './components/layout/gd-scrol
 export type { BoxStyleValue, LayoutStyles } from './components/layout/layout-element';
 export { GdThemeProvider, type ThemeChangeDetail } from './components/providers/gd-theme-provider/gd-theme-provider';
 export { GdThemedElement, ThemeConsumerController, type ThemeLike } from './core';
+
+// Bundled GridKit default theme, so consumers do not need to install `gd-design-library`.
+export { defaultTheme } from 'gd-design-library/tokens';
diff --git a/libs/web-components/stories/Overview.stories.ts b/libs/web-components/stories/Overview.stories.ts
index b810e80..50bb527 100644
--- a/libs/web-components/stories/Overview.stories.ts
+++ b/libs/web-components/stories/Overview.stories.ts
@@ -36,14 +36,13 @@ const meta = {
         </p>
 
         <h2>Install and register</h2>
-        <p>Install the component package and the GridKit design tokens in your application:</p>
-        <pre><code>npm install web-components gd-design-library</code></pre>
+        <p>Install the component package in your application. It is standalone: the GridKit design tokens and icons are bundled in, so you do not need to install <code>gd-design-library</code>.</p>
+        <pre><code>npm install web-components</code></pre>
         <p>
           Import the package once in your application entry point. The import registers every
-          <code>gd-*</code> custom element with the browser.
+          <code>gd-*</code> custom element with the browser and exposes the bundled <code>defaultTheme</code>.
         </p>
-        <pre><code>import 'web-components';
-import { defaultTheme } from 'gd-design-library/tokens';</code></pre>
+        <pre><code>import { defaultTheme } from 'web-components';</code></pre>
 
         <h2>How values and events work</h2>
         <ul>
@@ -78,7 +77,7 @@ import 'web-components';
 
 // app.component.ts
 import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
-import { defaultTheme } from 'gd-design-library/tokens';
+import { defaultTheme } from 'web-components';
 
 @Component({
   selector: 'app-root',
@@ -127,7 +126,7 @@ import App from './App.vue';
 createApp(App).mount('#app');</code></pre>
         <pre><code>&lt;script setup lang="ts"&gt;
 import { ref } from 'vue';
-import { defaultTheme } from 'gd-design-library/tokens';
+import { defaultTheme } from 'web-components';
 
 const email = ref('');
 const accepted = ref(false);
diff --git a/libs/web-components/vite.config.ts b/libs/web-components/vite.config.ts
index ef6cf32..5ed663d 100644
--- a/libs/web-components/vite.config.ts
+++ b/libs/web-components/vite.config.ts
@@ -3,39 +3,32 @@ import dts from 'vite-plugin-dts';
 import * as path from 'path';
 import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin';
 
-export default defineConfig(({ command }) => ({
+export default defineConfig({
   root: __dirname,
   cacheDir: '../../node_modules/.vite/libs/web-components',
   plugins: [nxViteTsPaths(), dts({ entryRoot: 'src', tsconfigPath: path.join(__dirname, 'tsconfig.lib.json') })],
   resolve: {
-    // Dev-server-only live-source aliasing for true single-source-of-truth: resolves straight
-    // to libs/ui/src/tokens (source, hot-reloaded) instead of gd-design-library's real package
-    // export map, which only resolves once libs/ui is built (dist/libs/ui/tokens). This is what
-    // makes editing libs/ui/src/tokens/button.ts instantly reflect in gd-button.ts without a
-    // `build:ui` step in between. Gated to `command === 'serve'` so the production build (below,
-    // `external: [/^gd-design-library(\/.*)?$/]`) still externalizes the real package instead of
-    // inlining the whole libs/ui source tree — the point of the dev alias is hot-reload
-    // ergonomics, not a production bundling strategy.
-    alias:
-      command === 'serve'
-        ? {
-            'gd-design-library/tokens': path.resolve(__dirname, '../ui/src/tokens/index.ts'),
-            'gd-design-library/icons': path.resolve(__dirname, '../ui/src/icons/index.ts'),
-            // The tokens barrel (above) re-exports every file in libs/ui/src/tokens, and those
-            // files resolve their OWN internal imports through libs/ui's own path aliases
-            // (@utils, @assets, etc. — see libs/ui/tsconfig.json). nxViteTsPaths() only
-            // reliably resolves this project's own tsconfig paths, not a foreign project's
-            // source pulled in transitively, so these are restated here (matching the
-            // tsconfig.json `paths` override, added for the same reason).
-            '@utils': path.resolve(__dirname, '../ui/src/utils'),
-            '@types': path.resolve(__dirname, '../ui/src/types'),
-            '@constants': path.resolve(__dirname, '../ui/src/constants'),
-            '@hooks': path.resolve(__dirname, '../ui/src/hooks'),
-            '@tokens': path.resolve(__dirname, '../ui/src/tokens'),
-            '@components': path.resolve(__dirname, '../ui/src/components'),
-            '@assets': path.resolve(__dirname, '../ui/src/assets'),
-          }
-        : {},
+    // Standalone package: `gd-design-library/tokens` and `/icons` are resolved to libs/ui source in
+    // BOTH dev and production, so the published bundle inlines the tokens, the icon catalog and the
+    // `@emotion/react` `keyframes` helper the tokens use. Consumers install only `web-components`
+    // and never need `gd-design-library`. Dev additionally gets hot reload of libs/ui/src/tokens.
+    //
+    // The tokens barrel re-exports every file in libs/ui/src/tokens, and those files resolve their
+    // OWN internal imports through libs/ui's path aliases (@utils, @assets, etc. — see
+    // libs/ui/tsconfig.json). nxViteTsPaths() only reliably resolves this project's own tsconfig
+    // paths, not a foreign project's source pulled in transitively, so they are restated here
+    // (matching the tsconfig.json `paths` override, added for the same reason).
+    alias: {
+      'gd-design-library/tokens': path.resolve(__dirname, '../ui/src/tokens/index.ts'),
+      'gd-design-library/icons': path.resolve(__dirname, '../ui/src/icons/index.ts'),
+      '@utils': path.resolve(__dirname, '../ui/src/utils'),
+      '@types': path.resolve(__dirname, '../ui/src/types'),
+      '@constants': path.resolve(__dirname, '../ui/src/constants'),
+      '@hooks': path.resolve(__dirname, '../ui/src/hooks'),
+      '@tokens': path.resolve(__dirname, '../ui/src/tokens'),
+      '@components': path.resolve(__dirname, '../ui/src/components'),
+      '@assets': path.resolve(__dirname, '../ui/src/assets'),
+    },
   },
   build: {
     outDir: '../../dist/libs/web-components',
@@ -47,11 +40,11 @@ export default defineConfig(({ command }) => ({
       formats: ['es'],
     },
     rollupOptions: {
-      external: [/^lit(\/.*)?$/, /^gd-design-library(\/.*)?$/],
+      external: [/^lit(\/.*)?$/, /^zustand(\/.*)?$/],
       output: {
         preserveModules: true,
         preserveModulesRoot: 'src',
       },
     },
   },
-}));
+});
diff --git a/package-lock.json b/package-lock.json
index 74a589e..0373eaa 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -22,10 +22,12 @@
         "ajv-formats": "^3.0.1",
         "core-js": "^3.36.1",
         "embla-carousel-react": "^8.6.0",
+        "gd-design-library": "^1.9.1",
         "react": "^18.3.1",
         "react-dom": "^18.3.1",
         "use-sync-external-store": "^1.5.0",
         "uuid": "^14.0.0",
+        "web-components": "^0.0.0",
         "zustand": "^5.0.6"
       },
       "devDependencies": {
diff --git a/package.json b/package.json
index 5fd3a3a..c4f2a0b 100644
--- a/package.json
+++ b/package.json
@@ -76,10 +76,12 @@
     "ajv-formats": "^3.0.1",
     "core-js": "^3.36.1",
     "embla-carousel-react": "^8.6.0",
+    "gd-design-library": "^1.9.1",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "use-sync-external-store": "^1.5.0",
     "uuid": "^14.0.0",
+    "web-components": "^0.0.0",
     "zustand": "^5.0.6"
   },
   "engines": {

From bec114fe88cd203a77d7475609835159300766cd Mon Sep 17 00:00:00 2001
From: Zlodej43sm <8863227+Zlodej43sm@users.noreply.github.com>
Date: Tue, 20 Oct 2026 16:24:37 +0200
Subject: [PATCH 3/3] refactor: inline token types and names to eliminate
 gd-design-library from published .d.ts files

Create `token-names.ts` with literal token-key lists (radius, checkbox sizes, typography variants, icons) so published type definitions stay self-contained without importing `gd-design-library`. Add `token-names.spec.ts` to validate lists match real tokens. Introduce `default-theme.ts` that re-exports `defaultTheme` with untyped token groups to prevent transitive imports. Configure Vite build with flat, readable output file names. Update harness files to consume built package from `dist/`.
---
 libs/web-components/harness/dark-theme.ts     |  4 +-
 .../harness/fidelity-check-vue.ts             |  7 +-
 libs/web-components/harness/fidelity-check.ts |  5 +-
 .../harness/form-participation-check.ts       |  7 +-
 .../harness/ssr-dsd-hydrate-check.ts          | 11 +--
 .../src/components/atoms/gd-icon/gd-icon.ts   |  3 +-
 libs/web-components/src/core/button.ts        |  3 +-
 libs/web-components/src/core/theme.ts         |  6 +-
 .../src/core/token-names.spec.ts              | 15 ++++
 libs/web-components/src/core/token-names.ts   | 84 +++++++++++++++++++
 libs/web-components/src/default-theme.ts      | 14 ++++
 libs/web-components/src/index.ts              |  2 +-
 libs/web-components/vite.config.ts            |  7 ++
 13 files changed, 145 insertions(+), 23 deletions(-)
 create mode 100644 libs/web-components/src/core/token-names.spec.ts
 create mode 100644 libs/web-components/src/core/token-names.ts
 create mode 100644 libs/web-components/src/default-theme.ts

diff --git a/libs/web-components/harness/dark-theme.ts b/libs/web-components/harness/dark-theme.ts
index 9dcba72..465db19 100644
--- a/libs/web-components/harness/dark-theme.ts
+++ b/libs/web-components/harness/dark-theme.ts
@@ -1,4 +1,6 @@
-import { defaultTheme } from 'gd-design-library/tokens';
+// Harness consumes the BUILT package (`nx build web-components`), exactly like an app would.
+// eslint-disable-next-line @nx/enforce-module-boundaries
+import { defaultTheme } from '../../../dist/libs/web-components/index.js';
 
 // Dark palette layered on the shared default theme, the same way an app would pass a second theme
 // to `ThemeProvider` in React. Text on the primary (yellow) fill stays dark via `text.black`.
diff --git a/libs/web-components/harness/fidelity-check-vue.ts b/libs/web-components/harness/fidelity-check-vue.ts
index 1fbdd89..4089a04 100644
--- a/libs/web-components/harness/fidelity-check-vue.ts
+++ b/libs/web-components/harness/fidelity-check-vue.ts
@@ -2,8 +2,11 @@
 // eslint-disable-next-line @nx/enforce-module-boundaries
 import '../../../dist/libs/ui/styles.css';
 import { createApp, h, onMounted, ref } from 'vue';
-import type { defaultTheme } from 'gd-design-library/tokens';
-import '../src/index';
+// Harness consumes the BUILT package (`nx build web-components`), exactly like an app would.
+// eslint-disable-next-line @nx/enforce-module-boundaries
+import '../../../dist/libs/web-components/index.js';
+// eslint-disable-next-line @nx/enforce-module-boundaries
+import type { defaultTheme } from '../../../dist/libs/web-components/index.js';
 import { darkTheme } from './dark-theme';
 
 type Item = { name: string; value: string };
diff --git a/libs/web-components/harness/fidelity-check.ts b/libs/web-components/harness/fidelity-check.ts
index c49037c..ae8c9a5 100644
--- a/libs/web-components/harness/fidelity-check.ts
+++ b/libs/web-components/harness/fidelity-check.ts
@@ -8,8 +8,9 @@ import { bootstrapApplication } from '@angular/platform-browser';
 // React Storybook baseline. Build it first with `npm run build:ui`.
 // eslint-disable-next-line @nx/enforce-module-boundaries
 import '../../../dist/libs/ui/styles.css';
-import { defaultTheme } from 'gd-design-library/tokens';
-import '../src/index';
+// Harness consumes the BUILT package (`nx build web-components`), exactly like an app would.
+// eslint-disable-next-line @nx/enforce-module-boundaries
+import { defaultTheme } from '../../../dist/libs/web-components/index.js';
 import { darkTheme } from './dark-theme';
 
 type Item = { name: string; value: string };
diff --git a/libs/web-components/harness/form-participation-check.ts b/libs/web-components/harness/form-participation-check.ts
index 77b6e54..6b1a095 100644
--- a/libs/web-components/harness/form-participation-check.ts
+++ b/libs/web-components/harness/form-participation-check.ts
@@ -14,10 +14,9 @@
  * never `evaluate_script` synthetic events: FINDINGS.md Section 6 documents a concrete false
  * negative from exactly that mistake.
  */
-import '../src/index';
-import { defaultTheme } from 'gd-design-library/tokens';
-import type { GdCheckbox } from '../src/components/atoms/gd-checkbox/gd-checkbox';
-import type { GdInput } from '../src/components/atoms/gd-input/gd-input';
+// Harness consumes the BUILT package (`nx build web-components`), exactly like an app would.
+// eslint-disable-next-line @nx/enforce-module-boundaries
+import { defaultTheme, type GdCheckbox, type GdInput } from '../../../dist/libs/web-components/index.js';
 
 const root = document.getElementById('root')!;
 
diff --git a/libs/web-components/harness/ssr-dsd-hydrate-check.ts b/libs/web-components/harness/ssr-dsd-hydrate-check.ts
index 0c51a47..4eeb038 100644
--- a/libs/web-components/harness/ssr-dsd-hydrate-check.ts
+++ b/libs/web-components/harness/ssr-dsd-hydrate-check.ts
@@ -1,11 +1,6 @@
-import '../src/components/atoms/gd-button/gd-button';
-import '../src/components/atoms/gd-avatar/gd-avatar';
-import '../src/components/atoms/gd-checkbox/gd-checkbox';
-import '../src/components/atoms/gd-input/gd-input';
-import '../src/components/atoms/gd-select/gd-select';
-import '../src/components/atoms/gd-typography/gd-typography';
-import '../src/components/molecules/gd-menu/gd-menu';
-import { defaultTheme } from 'gd-design-library/tokens';
+// Harness consumes the BUILT package (`nx build web-components`), exactly like an app would.
+// eslint-disable-next-line @nx/enforce-module-boundaries
+import { defaultTheme } from '../../../dist/libs/web-components/index.js';
 
 /**
  * Companion script for ssr-dsd-hydrated.html — checks what actually happens once Lit's
diff --git a/libs/web-components/src/components/atoms/gd-icon/gd-icon.ts b/libs/web-components/src/components/atoms/gd-icon/gd-icon.ts
index 686e253..3403f4c 100644
--- a/libs/web-components/src/components/atoms/gd-icon/gd-icon.ts
+++ b/libs/web-components/src/components/atoms/gd-icon/gd-icon.ts
@@ -3,8 +3,9 @@ import { customElement, property } from 'lit/decorators.js';
 import { styleMap } from 'lit/directives/style-map.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
 import { icon } from 'gd-design-library/tokens';
-import { iconCatalog, type GridKitIconName } from 'gd-design-library/icons';
+import { iconCatalog } from 'gd-design-library/icons';
 import { buttonCssBlockToText, get, resolveThemeTree, type ButtonCssBlock } from '../../../core';
+import type { GridKitIconName } from '../../../core/token-names';
 import { GdLayoutElement } from '../../layout/layout-element';
 
 type IconSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl';
diff --git a/libs/web-components/src/core/button.ts b/libs/web-components/src/core/button.ts
index 4d6bdc0..f6f544b 100644
--- a/libs/web-components/src/core/button.ts
+++ b/libs/web-components/src/core/button.ts
@@ -2,12 +2,13 @@ import { radius } from 'gd-design-library/tokens';
 import { get } from './get';
 import type { ButtonCssBlock } from './css';
 import type { ThemeLike } from './theme';
+import type { RadiusName } from './token-names';
 
 /** Mirrors gd-design-library's `ButtonVariant` enum values (libs/ui/src/components/atoms/types). */
 export type ButtonVariantName = 'primary' | 'secondary' | 'tertiary' | 'outlined' | 'text' | 'inherit';
 
 /** Mirrors gd-design-library's `ButtonStyledProps['$rounded']` (libs/ui/src/components/atoms/Button/Button.types.ts). */
-export type ButtonRoundedName = keyof typeof radius;
+export type ButtonRoundedName = RadiusName;
 
 export interface ButtonTokenTree {
   default: ButtonCssBlock;
diff --git a/libs/web-components/src/core/theme.ts b/libs/web-components/src/core/theme.ts
index b4f1670..c9911e2 100644
--- a/libs/web-components/src/core/theme.ts
+++ b/libs/web-components/src/core/theme.ts
@@ -1,4 +1,4 @@
-import type { checkbox, typography } from 'gd-design-library/tokens';
+import type { CheckboxSizeKey, TypographyStyleVariantKey } from './token-names';
 
 /**
  * Structural subset of gd-design-library's theme shape, covering only the token groups the
@@ -16,7 +16,7 @@ export interface ThemeLike {
 }
 
 /** `checkbox.size` keys in `libs/ui/src/tokens/checkbox.ts` (mirrors React's `CheckboxSize`). */
-export type CheckboxSizeName = keyof typeof checkbox.size;
+export type CheckboxSizeName = CheckboxSizeKey;
 
 /** Colour scale shared by Input and Select (`primary` is the default border; see `input.ts` tokens). */
 export type InputColorVariantName = 'primary' | 'success' | 'warning' | 'error';
@@ -38,4 +38,4 @@ export type TypographyVariantName =
   | 'kbd';
 
 /** `typography.styleVariant` keys in `libs/ui/src/tokens/typography.ts`. */
-export type TypographyStyleVariantName = keyof typeof typography.styleVariant;
+export type TypographyStyleVariantName = TypographyStyleVariantKey;
diff --git a/libs/web-components/src/core/token-names.spec.ts b/libs/web-components/src/core/token-names.spec.ts
new file mode 100644
index 0000000..ee1019b
--- /dev/null
+++ b/libs/web-components/src/core/token-names.spec.ts
@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'vitest';
+import { checkbox, radius, typography } from 'gd-design-library/tokens';
+import { iconCatalog } from 'gd-design-library/icons';
+import { CHECKBOX_SIZE_NAMES, ICON_NAMES, RADIUS_NAMES, TYPOGRAPHY_STYLE_VARIANT_NAMES } from './token-names';
+
+describe('token-names', () => {
+  it.each([
+    ['radius', RADIUS_NAMES, radius],
+    ['checkbox.size', CHECKBOX_SIZE_NAMES, checkbox.size],
+    ['typography.styleVariant', TYPOGRAPHY_STYLE_VARIANT_NAMES, typography.styleVariant],
+    ['iconCatalog', ICON_NAMES, iconCatalog],
+  ])('%s names match the real tokens', (_label, names, tokens) => {
+    expect([...names].sort()).toEqual(Object.keys(tokens).sort());
+  });
+});
diff --git a/libs/web-components/src/core/token-names.ts b/libs/web-components/src/core/token-names.ts
new file mode 100644
index 0000000..b2aef7e
--- /dev/null
+++ b/libs/web-components/src/core/token-names.ts
@@ -0,0 +1,84 @@
+/**
+ * Literal token-key lists behind the public `*Name` types.
+ *
+ * They mirror keys of `gd-design-library/tokens` and `/icons`. They are written out here instead of
+ * derived with `keyof typeof <tokens>` so the published `.d.ts` files stay self-contained: a derived
+ * type would make them import `gd-design-library`, which standalone consumers do not install.
+ * `token-names.spec.ts` fails when these lists drift from the real tokens.
+ */
+export const RADIUS_NAMES = ['none', 'default', 'xs', 'sm', 'md', 'lg', 'xl', 'round'] as const;
+export const CHECKBOX_SIZE_NAMES = ['sm', 'md'] as const;
+export const TYPOGRAPHY_STYLE_VARIANT_NAMES = [
+  'light',
+  'normal',
+  'semibold',
+  'bold',
+  'italic',
+  'small',
+  'uppercase',
+  'lowercase',
+  'underline',
+  'strike',
+] as const;
+export const ICON_NAMES = [
+  'cross',
+  'success',
+  'error',
+  'warning',
+  'info',
+  'dot',
+  'check',
+  'arrowDown',
+  'arrowRight',
+  'arrowLeft',
+  'mobileMenu',
+  'home',
+  'slash',
+  'arrowForward',
+  'localShipping',
+  'favorite',
+  'favoriteOutlined',
+  'deleteOutlined',
+  'accountCircle',
+  'shoppingBag',
+  'errorOutline',
+  'star',
+  'starOutlined',
+  'starHalf',
+  'minus',
+  'plus',
+  'filter',
+  'ruler',
+  'processing',
+  'paymentCard',
+  'eye',
+  'attachment',
+  'upload',
+  'folder',
+  'folderOpen',
+  'wifiTethering',
+  'portrait',
+  'search',
+  'edit',
+  'volumeUp',
+  'contentCopy',
+  'thumbUp',
+  'thumbDown',
+  'fileCopy',
+  'keyboardArrowDown',
+  'keyboardArrowUp',
+  'send',
+  'thumbUpFilled',
+  'thumbDownFilled',
+  'chat',
+  'chatBubble',
+  'phone',
+  'mic',
+  'fullscreen',
+  'fullscreenExit',
+] as const;
+
+export type RadiusName = (typeof RADIUS_NAMES)[number];
+export type CheckboxSizeKey = (typeof CHECKBOX_SIZE_NAMES)[number];
+export type TypographyStyleVariantKey = (typeof TYPOGRAPHY_STYLE_VARIANT_NAMES)[number];
+export type GridKitIconName = (typeof ICON_NAMES)[number];
diff --git a/libs/web-components/src/default-theme.ts b/libs/web-components/src/default-theme.ts
new file mode 100644
index 0000000..1785455
--- /dev/null
+++ b/libs/web-components/src/default-theme.ts
@@ -0,0 +1,14 @@
+import { defaultTheme as tokensDefaultTheme } from 'gd-design-library/tokens';
+import type { ThemeLike } from './core';
+
+/* eslint-disable @typescript-eslint/no-explicit-any -- token groups are intentionally untyped, see below */
+/**
+ * Shape of the bundled default theme. The token groups are typed `any` on purpose: typing them
+ * as `typeof` the real tokens would make the published `.d.ts` import `gd-design-library`, which
+ * standalone consumers do not install. Custom themes can still spread and override any group.
+ */
+export type DefaultTheme = ThemeLike & { colors: any; font: any; spacing: any; radius: any; values: any };
+/* eslint-enable @typescript-eslint/no-explicit-any */
+
+/** GridKit default theme, inlined into this package so `gd-design-library` is not required. */
+export const defaultTheme: DefaultTheme = tokensDefaultTheme as unknown as DefaultTheme;
diff --git a/libs/web-components/src/index.ts b/libs/web-components/src/index.ts
index 093ca02..6f66720 100644
--- a/libs/web-components/src/index.ts
+++ b/libs/web-components/src/index.ts
@@ -38,4 +38,4 @@ export { GdThemeProvider, type ThemeChangeDetail } from './components/providers/
 export { GdThemedElement, ThemeConsumerController, type ThemeLike } from './core';
 
 // Bundled GridKit default theme, so consumers do not need to install `gd-design-library`.
-export { defaultTheme } from 'gd-design-library/tokens';
+export { defaultTheme, type DefaultTheme } from './default-theme';
diff --git a/libs/web-components/vite.config.ts b/libs/web-components/vite.config.ts
index 5ed663d..bd8b5ed 100644
--- a/libs/web-components/vite.config.ts
+++ b/libs/web-components/vite.config.ts
@@ -42,6 +42,13 @@ export default defineConfig({
     rollupOptions: {
       external: [/^lit(\/.*)?$/, /^zustand(\/.*)?$/],
       output: {
+        // Flat, readable file names. The package entry must be `index.js` so it matches `main` in
+        // package.json; every other preserved module is flattened to `<path_with_underscores>.js`
+        // (libs/ui token modules inlined from the tokens barrel land here too).
+        entryFileNames: (chunk) =>
+          chunk.name === 'web-components/src/index'
+            ? 'index.js'
+            : `${chunk.name.replace(/^web-components\/src\//, '').replace(/[^\w.-]/g, '_')}.js`,
         preserveModules: true,
         preserveModulesRoot: 'src',
       },