gd-design-library 1.8.2 → 1.8.3

package/README.md

@@ -2,563 +2,188 @@
 
 ![GridKit Logo](https://unpkg.com/gd-design-library/gridKit_logo.png)
 
-**GridKit** is the official design system and component library from Grid Dynamics.  
-It provides a set of reusable, accessible, and themeable React UI components designed to accelerate the development of consistent, scalable applications – with a focus on e-commerce and enterprise platforms.
+**GridKit** is Grid Dynamics' official React component library — 64 accessible, themeable components built for e-commerce and enterprise applications. It connects directly to Figma design tokens and includes a built-in AI layer that lets LLMs generate and render UI at runtime.
 
----
-
-## ✨ Features
-
-- 🧩 64 modular components (atoms, molecules, organisms, layout)
-- 🎨 Theming support with dynamic runtime switching
-- 🔗 Design tokens synced with Figma
-- 📦 Optimized build using Vite
-- 📚 Fully documented via Storybook
-- ♿ WCAG 2.1 AA-compliant components
-- ⚙️ Type-safe and fully tested with Vitest + RTL
-- 🤖 Built-in AI integration — LLM → React/TSX code generation or A2UI JSON spec rendering
-- 🔄 A2UI mode: LLMs generate structured JSON specs validated against `ui-specification-schema.json`, rendered at runtime by `renderA2UISpec` with zero custom JSX
-- 🎯 `buildA2UISystemPrompt` keeps LLM instructions in sync with the live component map — no manual prompt maintenance
-- 🔌 Action system: define `A2UIActionDefinition[]` once, share between `buildA2UISystemPrompt` (LLM constraint) and `renderA2UISpec` (runtime handler wiring)
+**Browse components:** [Storybook](https://storybook.cto-rnd-system-design.griddynamics.net)
 
 ---
 
-## 📦 Installation
-
-Start by ensuring that you already have `@emotion/react` and `@emotion/styled` installed. Then, run one of the following commands to install the dependencies:
-
-```bash
-npm install gd-design-library @emotion/styled @emotion/react
-# or
-yarn add gd-design-library @emotion/styled @emotion/react
-```
-
----
-
-## 🧑‍💻 Getting Started
-
-### Prerequisites
-
-- Node.js (22.17.0 or higher)
-- Yarn or npm
-
-### Clone & Install
-
-```bash
-git clone https://github.com/griddynamics/cto-rnd-system-design.git
-cd gd-design-system
-yarn install
-```
-
----
-
-## 🚀 Development
-
-Start the local dev server with Vite:
-
-```bash
-yarn dev
-```
-
-Open [http://localhost:5173](http://localhost:5173) in your browser.
-
-### Run Storybook
-
-```bash
-yarn storybook
-```
-
----
-
-## 🏗️ Project Structure
-
-```bash
-gd-design-system/
-├── src/
-│   ├── components/
-│   │   ├── atoms/              # 21 basic building blocks (Button, Input, etc.)
-│   │   ├── molecules/          # 18 simple combinations (Accordion, Table, etc.)
-│   │   ├── organisms/          # 10 complex sections (Card, Chart, Modal, etc.)
-│   │   └── layout/             # 6 structural components (Row, Column, FlexContainer, etc.)
-│   ├── ai/                    # AI integration system (code mode + A2UI mode)
-│   ├── tokens/                 # Design tokens from Figma
-│   ├── hooks/                  # Shared React hooks
-│   └── utils/                  # Utility functions
-├── .storybook/                 # Storybook config
-├── vite.config.ts              # Vite config
-├── tsconfig.json               # TypeScript config
-├── README.md
-```
-
----
-
-## 🧪 Testing & Linting
-
-### Run Tests
-
-```bash
-yarn test
-```
-
-### Lint Code
-
-```bash
-yarn lint
-```
-
-### Format Code
-
-```bash
-yarn format
-```
-
-### Check Formatting
+## At a glance
 
-```bash
-yarn format:check
-```
+|                |                                                     |
+| -------------- | --------------------------------------------------- |
+| Components     | 64 — atoms, molecules, organisms, layout            |
+| Theming        | Runtime switching, Figma-synced design tokens       |
+| Accessibility  | WCAG 2.1 AA                                         |
+| AI integration | LLM → React/TSX code **or** A2UI JSON → rendered UI |
+| Testing        | Vitest + React Testing Library                      |
+| Build          | Vite, ESM + CJS, tree-shakeable                     |
 
 ---
 
-## 🔍 Build Verification
-
-GridKit ships a 5-phase verification pipeline that runs automatically after every `yarn build:ui`. It checks that the published package works correctly for all consumers — ESM, CJS, SSR, and tree-shaking.
-
-### Commands
-
-| Command          | What it does                                                          |
-| ---------------- | --------------------------------------------------------------------- |
-| `yarn build:ui`  | Full build → phases 1–5 → summary                                     |
-| `yarn verify:ui` | Phases 1–5 + summary, skips rebuild — use after an existing build     |
-| `yarn view:ui`   | Generates `report.html` from JSON reports and opens it in the browser |
-
-`yarn build:ui` runs in order: readme stats check → AI docs generation → type-check → lint → Vite build → all 5 phases → combined terminal summary.
-
-`yarn view:ui` can be run any time after `yarn verify:ui` (or `yarn build:ui`) has written JSON reports to `libs/ui/scripts/output/`. It opens a dark-theme HTML dashboard with charts and tables for every phase — no server needed.
-
-### Visual dashboard
-
-```bash
-yarn verify:ui && yarn view:ui
-# or after a full build:
-yarn build:ui && yarn view:ui
-```
-
-The dashboard (`libs/ui/scripts/output/report.html`) includes:
-
-- **Overview** — totals banner, 5 phase status cards, summary charts
-- **Phase 1** — exports by category (donut), dependency status (pie), warnings table
-- **Phase 2** — violations list, per-component KB footprint bar chart (yellow = cross-component deps)
-- **Phase 3** — errors with full publint issue list, warnings by type (pie), circular deps breakdown
-- **Phase 4** — RSC readiness donut, browser globals by context (pie), unguarded globals table (file · line · global · context)
-- **Phase 5** — CJS errors and warnings
-
-To generate without opening: `node libs/ui/scripts/view-reports.mjs --no-open`
-
-### What each phase checks
-
-| Phase                | Script                | Checks                                                                                                                                                                        |
-| -------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 1 · Public API Audit | `audit-api.mjs`       | All exported symbols traceable from `src/index.ts`; undeclared / unused / bundled deps; exports gap in `package.json`                                                         |
-| 2 · Tree-Shaking     | `treeshake-check.mjs` | Import graph built from `dist/`; cross-component contamination per probe; `sideEffects` field; per-component KB footprint                                                     |
-| 3 · Build Lint       | `build-lint.mjs`      | Circular imports (structural vs barrel); `package.json` exports validity; `.d.ts` completeness; private/internal leaks; `"use client"` consistency; `publint` standards check |
-| 4 · SSR Safety       | `ssr-check.mjs`       | Node.js `import()` test; unguarded browser globals; RSC `"use client"` coverage; Emotion SSR guidance                                                                         |
-| 5 · CJS Verification | `cjs-check.mjs`       | `.cjs` output exists; `require()` works in Node.js; `exports` map has `"require"` conditions; `.cjs` uses CommonJS syntax; `"main"` field points to CJS                       |
-
-### Terminal summary
-
-After all phases run, a combined table is printed:
-
-```text
-╔══════════════════════════════════════════════════╗
-║   gd-design-library  ·  Build Verify Summary    ║
-╚══════════════════════════════════════════════════╝
-
-  Phase 1  ✓  Public API Audit        142 exports · 0 warnings
-  Phase 2  ✓  Tree-Shaking Check      0 violations
-  Phase 3  ⚠  Build Lint              0 errors · 3 warnings
-  Phase 4  ✓  SSR Safety Check        0 errors · 0 warnings
-  Phase 5  ✗  CJS Verification        1 errors · 0 warnings
-
-── Totals ──────────────────────────────────────────
-  Errors      : 1
-  Warnings    : 3
-  Violations  : 0
-```
-
-Status icons: `✓` pass · `⚠` warnings only · `✗` errors · `–` report not found (phase was not run).
-
-### Investigating failures
+## Quick start
 
-**Visual dashboard** — easiest way to explore all phases at once:
+### 1. Install
 
 ```bash
-yarn view:ui
-```
-
-**Run a phase directly** — full console output with file paths and line numbers:
-
-```bash
-node libs/ui/scripts/treeshake-check.mjs   # Phase 2
-node libs/ui/scripts/build-lint.mjs        # Phase 3
-node libs/ui/scripts/ssr-check.mjs         # Phase 4
-
-# --verbose for full import chains / all global usages:
-node libs/ui/scripts/treeshake-check.mjs --verbose
-node libs/ui/scripts/ssr-check.mjs --verbose
-```
-
-Or via nx:
-
-```bash
-nx run ui:treeshake-check
-nx run ui:build-lint
-nx run ui:ssr-check
-```
-
-**Read the JSON report** directly — already written by `yarn verify:ui`:
-
-```bash
-cat libs/ui/scripts/output/treeshake-report.json   # Phase 2 — "violations"
-cat libs/ui/scripts/output/build-lint-report.json  # Phase 3 — "errors", "warnings"
-cat libs/ui/scripts/output/ssr-report.json         # Phase 4 — "errors", "warnings"
-```
-
-### JSON reports
-
-Each phase writes to `libs/ui/scripts/output/`:
-
-| File                     | Phase | Key fields                                                  |
-| ------------------------ | ----- | ----------------------------------------------------------- |
-| `public-api-map.json`    | 1     | `totalExports`, `byCategory`, `exports`                     |
-| `deps-map.json`          | 1     | `analysis.undeclared`, `analysis.unusedDeps`, `warnings`    |
-| `treeshake-report.json`  | 2     | `violations`, `probes`, `buildFormats`                      |
-| `build-lint-report.json` | 3     | `errors`, `warnings`, `circularDeps`                        |
-| `ssr-report.json`        | 4     | `errors`, `warnings`, `nodeImport`, `browserGlobals`, `rsc` |
-| `cjs-report.json`        | 5     | `errors`, `warnings`                                        |
-| `report.html`            | all   | visual dashboard generated by `yarn view:ui`                |
-
-### CI usage
-
-Use `nx run ui:verify` for CI — runs all 5 phases with `--check` (exits 1 on any error) and `--json`:
-
-```bash
-nx run ui:verify
-```
-
-Individual phase targets:
-
-```bash
-nx run ui:audit-api          # Phase 1
-nx run ui:treeshake-check    # Phase 2
-nx run ui:build-lint         # Phase 3
-nx run ui:ssr-check          # Phase 4
-nx run ui:cjs-check          # Phase 5
-nx run ui:view-reports       # open dashboard (reads existing JSON reports)
-```
-
----
-
-## 🧰 Component Generator
-
-Use our CLI script to quickly scaffold new components:
-
-### Add Execution Permission (first time)
-
-```bash
-chmod +x ./bin/create-component.js
-```
-
-### Create a Component
-
-```bash
-yarn crc ButtonGroup
+npm install gd-design-library @emotion/styled @emotion/react
 ```
 
-You’ll be prompted to select:
-
-- `core`
-- `domainSpecific`
-
-The script will generate boilerplate files and update exports automatically.
-
----
-
-## 🧩 Usage
-
-Wrap your app in the `ThemeProvider` with `isDefault` to apply default GD global styles and tokens:
+### 2. Wrap your app
 
 ```tsx
 import { ThemeProvider } from 'gd-design-library';
-// OPTIONAL: default GD global styles, reset, font.
-import 'gd-design-library/styles.css';
+import 'gd-design-library/styles.css'; // optional: GD global styles, reset, fonts
 
 function App() {
   return (
     <ThemeProvider isDefault>
-      <YourAppRoutes />
+      <YourApp />
     </ThemeProvider>
   );
 }
 ```
 
-or `initialTheme` to install custom one as default initially
-
-```json
-{
-  "name": "myCustomTheme",
-  "componentAStyles": {
-    "style": "value"
-  }
-}
-```
+### 3. Use a component
 
 ```tsx
-import { ThemeProvider, defaultTheme } from 'gd-design-library';
-import myCustomTheme from 'PROJECT_PATH/myCustomTheme'; // JSON or any js/ts and similliar with object return
+import { Button, Typography } from 'gd-design-library';
 
-const App = () => {
-  // In case you want extend default theme, by overwriting only particular components
-  const initialTheme = Object.assign({}, defaultTheme, myCustomTheme);
+function Hero() {
   return (
-    <ThemeProvider initialTheme={initialTheme}>
-      <YourAppRoutes />
-    </ThemeProvider>
+    <>
+      <Typography variant="h1">Hello GridKit</Typography>
+      <Button variant="primary" onClick={() => alert('clicked')}>
+        Get started
+      </Button>
+    </>
   );
-};
+}
 ```
 
-You can now use components like this:
+That's it. Open [Storybook](https://storybook.cto-rnd-system-design.griddynamics.net) to browse all 64 components with live props and code samples.
 
-```tsx
-import { Button } from 'gd-design-library';
+---
 
-<Button variant="primary">Click me</Button>;
-```
+## Theming
 
-## Adding new theme
+### Use the built-in default theme
 
-Here’s a minimal React app example showing how to create and apply custom theme based on default, exactly like in your snippet.
-Example structure:
+Pass `isDefault` to `ThemeProvider` — applies GD tokens and global styles automatically.
 
-- `main.tsx`: wraps the app with `ThemeProvider`
+```tsx
+<ThemeProvider isDefault>
+  <App />
+</ThemeProvider>
+```
+
+### Extend the default theme
+
+Override only the tokens you need. Everything else inherits from `defaultTheme`.
 
 ```tsx
-import React from 'react';
-import ReactDOM from 'react-dom/client';
-import App from './App';
+import { ThemeProvider, defaultTheme } from 'gd-design-library';
+import myBrandTokens from './myBrandTokens';
 
-import { ThemeProvider } from 'gd-design-library';
+const theme = { ...defaultTheme, ...myBrandTokens };
 
-ReactDOM.createRoot(document.getElementById('root')!).render(
-  <React.StrictMode>
-    <ThemeProvider isDefault>
-      <App />
-    </ThemeProvider>
-  </React.StrictMode>
-);
+<ThemeProvider initialTheme={theme}>
+  <App />
+</ThemeProvider>;
 ```
 
-- `useCustomTheme.tsx`: theme hook
+### Switch themes at runtime
 
-\*\* Can be used on top level instead `isDefault`, use `initialTheme`, based on `updateThemeTokens` & `defaultTheme` from hook snippet
+Use the `useTheme` hook and `updateThemeTokens` to create and activate a custom theme dynamically.
 
 ```tsx
 import { useEffect } from 'react';
 import { updateThemeTokens, defaultTheme, useTheme } from 'gd-design-library';
 
-export default function useCustomTheme() {
+export function useCustomTheme() {
   const { addTheme, setTheme } = useTheme();
-  const customTheme = {
-    ...defaultTheme,
-    name: 'CustomTheme',
-  };
+
   useEffect(() => {
-    // Customise tokens
-    updateThemeTokens(customTheme, {
-      'select.dropdown': {
-        backgroundColor: 'red',
-        borderRadius: '10px',
-        boxShadow: '0 0 10px rgba(0, 0, 0, 0.1)',
-        padding: '10px',
-        width: '200px',
-        height: '200px',
-        zIndex: 1000,
-        position: 'absolute',
-        top: '50%',
-        left: '50%',
-      },
-      // any other theme overwrites here
-      'button.default': {
-        borderRadius: '32px',
-      },
-      'chatbubble.question': {
-        background: '#F1F5FA',
-      },
+    const custom = { ...defaultTheme, name: 'brand' };
+
+    updateThemeTokens(custom, {
+      'button.default': { borderRadius: '32px' },
+      'select.dropdown': { backgroundColor: '#f5f5f5', borderRadius: '8px' },
     });
-    // Add customTheme in a theme scope
-    addTheme(customTheme.name, customTheme);
-    //Set customTheme as an active, optional on demand to apply as an active
-    setTheme(customTheme.name);
+
+    addTheme(custom.name, custom);
+    setTheme(custom.name);
   }, []);
 }
 ```
 
-- `App.tsx`: renders a `Select` to demonstrate the change
-
-```tsx
-import React from 'react';
-
-import { FlexContainer, Typography, Row, Select, type Option } from 'gd-design-library';
-
-import useCustomTheme from './useCustomTheme';
-
-const items: Option[] = [
-  { name: 'Option 1', value: 'option1' },
-  { name: 'Option 2', value: 'option2' },
-  { name: 'Option 3', value: 'option3' },
-];
+Call `useCustomTheme()` anywhere in your tree — components update immediately.
 
-export default function App() {
-  useCustomTheme();
+**Token shape example** (`myBrandTokens.json`):
 
-  return (
-    <FlexContainer>
-      <Typography>Custom Themed Select</Typography>
-      <Row>
-        <Select items={items} />
-      </Row>
-    </FlexContainer>
-  );
+```json
+{
+  "name": "brand",
+  "button.default": { "borderRadius": "4px" },
+  "chatbubble.question": { "background": "#F1F5FA" }
 }
 ```
 
 ---
 
-## 🤖 AI Integration
-
-GridKit ships a built-in AI integration layer at [`./ai`](./ai/README.md) that lets LLMs generate UI — either as **React/TSX code** or as **A2UI JSON specs** rendered at runtime.
-
-```text
-./ai/
-├── README.md                        # AI integration overview
-├── PROMPT_USAGE_MANUAL.md           # Full prompt usage guide
-├── index.d.ts                       # Main exports (code mode + A2UI mode)
-├── prompts.d.ts                     # buildClaudeSystemPrompt, buildGPT4Prompt, buildGeminiPrompt
-├── discovery.d.ts                   # Component discovery utilities
-├── validation.d.ts                  # Schema & generated-code validation
-├── a2ui/                            # A2UI JSON spec mode
-│   ├── A2UI_PROTOCOL.md             # Protocol specification
-│   ├── index.d.ts                   # A2UI exports
-│   ├── component-map.d.ts           # A2UI type → GridKit component mapping
-│   ├── system-prompt.d.ts           # buildA2UISystemPrompt(), buildA2UIGeminiRequest()
-│   ├── spec-schema.d.ts             # A2UISpec TypeScript types
-│   └── ui-specification-schema.json # AJV/Gemini responseSchema
-└── schemas/                         # Component AI schemas (52 components)
-    ├── index.d.ts
-    ├── components.d.ts
-    ├── components/                  # Per-component schemas
-    └── hooks/
-        └── useTheme.d.ts
-```
-
-See [`./ai/README.md`](./ai/README.md) for full documentation.
-
----
-
-## 🔄 A2UI Mode — LLM → JSON → UI
+## AI integration — A2UI
 
-A2UI (Agent-to-UI) is a JSON protocol where an LLM produces a structured spec and GridKit renders it at runtime — no JSX required on the consuming side.
+A2UI (Agent-to-UI) lets an LLM output a structured JSON spec. GridKit renders it as real React components — no JSX on your side.
 
-### Two functions, one shared contract
+### How it works
 
-| Function                          | Role                                                                                                                             |
-| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `buildA2UISystemPrompt(options?)` | Generates the LLM system instruction from the live component map. Injects your `actions` as the only available action types.     |
-| `renderA2UISpec(spec, actions?)`  | Takes a validated `A2UISpec` and renders it as React components. Wires action `handler` callbacks from the same `actions` array. |
-
-Pass the **same `A2UIActionDefinition[]` array** to both — it is the single source of truth for what actions the LLM can emit and what your app will handle.
-
-### `buildA2UISystemPrompt`
-
-```typescript
-import { buildA2UISystemPrompt } from 'gd-design-library/ai';
-
-const systemInstruction = buildA2UISystemPrompt({
-  agentId: 'shop-agent',
-  agentName: 'Shop Assistant',
-  context: 'E-commerce product catalog assistant for MyShop.',
-  imageSources: ['cdn.myshop.com'],
-  locale: 'en-US',
-  actions: [
-    {
-      type: 'add-to-cart',
-      description: 'Add a product to the cart. payload: { productId: string, quantity: number }',
-      handler: ({ payload }) => addToCart(payload),
-    },
-    {
-      type: 'open-checkout',
-      description: 'Navigate to the checkout flow. No payload required.',
-      handler: () => navigate('/checkout'),
-    },
-  ],
-});
+```text
+User message → LLM (with system prompt from buildA2UISystemPrompt)
+                    → A2UISpec JSON (validated against schema)
+                          → renderA2UISpec → React components
 ```
 
-Key options:
+Two functions, one shared `actions` array:
 
-| Option                  | Description                                                                      |
-| ----------------------- | -------------------------------------------------------------------------------- |
-| `agentId` / `agentName` | Identifiers placed in every generated spec's `metadata`                          |
-| `context`               | Free-form use-case description injected near the top of the prompt               |
-| `actions`               | App-defined action types — the **only** way to make actions available to the LLM |
-| `imageSources`          | Restrict image `src` hosts; pass `[]` to disable remote images entirely          |
-| `locale`                | BCP 47 locale code; auto-selects EU/US price formatting                          |
-| `priceFormat`           | `'us'` · `'eu'` · or a `PriceFormatCustom` object for full control               |
-| `customGuardrails`      | Extra guardrail rules appended after the system-defined ones                     |
-| `customRules`           | Extra generation rules appended after the system-defined ones                    |
-| `theme`                 | `'light'` (default) · `'dark'` · `'auto'`                                        |
+| Function                         | What it does                                                                                    |
+| -------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `buildA2UISystemPrompt(options)` | Generates the LLM system instruction. Injects your `actions` as the only callable action types. |
+| `renderA2UISpec(spec, actions)`  | Maps the validated JSON spec to GridKit components and wires action handlers.                   |
 
-### `renderA2UISpec`
+### Minimal example
 
 ```tsx
-import { renderA2UISpec } from 'gd-design-library';
+import { buildA2UISystemPrompt, renderA2UISpec } from 'gd-design-library/ai';
 import type { A2UIActionDefinition } from 'gd-design-library/ai';
 
+// Define actions once — shared by prompt builder and renderer
 const actions: A2UIActionDefinition[] = [
   {
     type: 'add-to-cart',
-    description: 'Add a product to the cart.',
+    description: 'Add a product to the cart. payload: { productId: string, quantity: number }',
     handler: ({ payload }) => addToCart(payload),
   },
 ];
 
+// Build the system prompt for your LLM
+const systemPrompt = buildA2UISystemPrompt({
+  agentId: 'shop-agent',
+  agentName: 'Shop Assistant',
+  context: 'E-commerce product catalog.',
+  actions,
+});
+
+// Render whatever the LLM returns
 function AgentResponse({ spec }) {
   return <>{renderA2UISpec(spec, actions)}</>;
 }
 ```
 
-`renderA2UISpec` maps every `A2UIComponent` in the spec to the corresponding GridKit component, resolves layout (vertical / horizontal / grid), and dispatches action callbacks when user events fire. Returns `null` for empty or invalid specs.
+### Gemini structured output
 
-### Schema validation — `ui-specification-schema.json`
+Pass the schema directly to `responseSchema` — the model returns valid JSON every time.
 
-Every A2UI response should be validated before rendering. The schema is exported from the package:
-
-```typescript
-import schema from 'gd-design-library/ai/ui-specification-schema.json';
-import Ajv from 'ajv';
-
-const ajv = new Ajv();
-const validate = ajv.compile(schema);
-
-if (!validate(spec)) {
-  console.error('Invalid A2UI spec:', validate.errors);
-}
-```
-
-For **Gemini** structured output, pass `A2UI_SPEC_SCHEMA` directly as `responseSchema` to enforce JSON shape at the model level:
-
-```typescript
+```tsx
 import { buildA2UIGeminiRequest, A2UI_SPEC_SCHEMA } from 'gd-design-library/ai';
 
 const model = genAI.getGenerativeModel({
@@ -573,25 +198,43 @@ const result = await model.generateContent(
   buildA2UIGeminiRequest('Show a product analytics dashboard', {
     agentId: 'analytics-agent',
     context: 'Product analytics for an e-commerce platform.',
+    actions,
   })
 );
 ```
 
-The schema enforces the full `A2UISpec` structure including `version`, `metadata`, `ui.layout`, `ui.components`, and `ui.actions`. The agent service retries up to 3 times on validation failure.
+### Validate before rendering
 
----
+```tsx
+import schema from 'gd-design-library/ai/ui-specification-schema.json';
+import Ajv from 'ajv';
 
-## 📘 Documentation
+const validate = new Ajv().compile(schema);
 
-Explore our hosted Storybook:
+if (!validate(spec)) {
+  console.error('Invalid A2UI spec:', validate.errors);
+}
+```
 
-👉 [https://storybook.cto-rnd-system-design.griddynamics.net](https://storybook.cto-rnd-system-design.griddynamics.net)
+Full reference: [`./ai/README.md`](./ai/README.md) and [`./ai/PROMPT_USAGE_MANUAL.md`](./ai/PROMPT_USAGE_MANUAL.md)
 
 ---
 
-## 📄 License
+## Project structure
+
+```text
+libs/ui/src/
+├── components/
+│   ├── atoms/       # 21 primitives — Button, Input, Badge, …
+│   ├── molecules/   # 18 composites — Accordion, Table, …
+│   ├── organisms/   # 10 sections — Card, Chart, Modal, …
+│   └── layout/      # 6 containers — Row, Column, FlexContainer, …
+├── ai/              # AI integration (code mode + A2UI mode)
+├── tokens/          # Design tokens (synced from Figma)
+├── hooks/           # Shared React hooks
+└── utils/           # Utility functions
+```
 
-© Grid Dynamics. All rights reserved.  
-This package is for internal and authorized client use only.
+## License
 
----
+© Grid Dynamics. All rights reserved. For internal and authorized client use only.