diff --git a/README.md b/README.md
index 3c2d550c..6fafc22f 100755
--- a/README.md
+++ b/README.md
@@ -37,6 +37,11 @@ Usage examples, migration notes, and per-component guidance live alongside the p
 `packages/ui/README.md` for code snippets and plugin setup instructions, or spin up Storybook (`yarn sb:serve`) and
 browse the stories locally.
 
+## Documentation
+
+For a complete handbook covering setup, theming, development workflow, testing, and release processes, see
+[`docs/README.md`](docs/README.md).
+
 OR **cypress component-testing:**
 
 ```shell
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 00000000..212bfbbf
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,52 @@
+# Soramitsu UI Library Documentation
+
+This directory gathers the practical knowledge required to work with the Soramitsu UI monorepo. Use it as a handbook whether you are onboarding, building an application with the published packages, or contributing new components to the design system.
+
+## Quick start checklist
+
+- Review [getting-started.md](getting-started.md) for prerequisites, environment setup, and the fastest way to spin up Storybook locally.
+- Skim [project-structure.md](project-structure.md) to understand how the monorepo is organised and where to place new work.
+- If you are consuming the library, jump to [components.md](components.md) for usage patterns and integration recipes.
+- If you are contributing, read [development-workflow.md](development-workflow.md) and [testing-and-quality.md](testing-and-quality.md) to align with the tooling and quality bars.
+- Customising themes or tokens? See [theming.md](theming.md) for the token architecture and Sass utilities.
+
+## Document map
+
+- [getting-started.md](getting-started.md) — installation, environment, and workshop-ready commands.
+- [project-structure.md](project-structure.md) — packages, folders, and how code flows between them.
+- [components.md](components.md) — consuming Soramitsu components, patterns, and API conventions.
+- [theming.md](theming.md) — tokens, typography presets, and runtime theming strategies.
+- [development-workflow.md](development-workflow.md) — day-to-day development loops, linting, and recommended toolchain integrations.
+- [testing-and-quality.md](testing-and-quality.md) — unit, visual, and integration testing plus accessibility checks.
+- [storybook.md](storybook.md) — Storybook configuration, authoring guidelines, and how to embed stories in downstream docs.
+- [release-management.md](release-management.md) — versioning, changesets, and publishing coordination.
+- [contributing.md](contributing.md) — collaboration standards, review expectations, and branch hygiene.
+- [troubleshooting.md](troubleshooting.md) — common issues, diagnostics, and escalation paths.
+- [scripts-reference.md](scripts-reference.md) — root-level and package-level scripts with when-to-use guidance.
+- [glossary.md](glossary.md) — shared vocabulary for design system discussions.
+- [backlog.md](backlog.md) — outstanding technical debt and follow-up tasks retained from the initial audit.
+
+## Core principles
+
+- **Design-system first.** Tokens, typography, and components are designed to stay in sync with Soramitsu’s design language. When in doubt, start from `@soramitsu-ui/theme` and align component styles with token contracts.
+- **Composable Vue 3 architecture.** Components rely on composition API patterns, provide/inject contracts, and a-la-carte imports to keep bundles lean.
+- **Story-driven development.** Storybook acts as the home for manual QA, visual review, and long-tail usage examples. Stories accompany every component change.
+- **Automation as guardrails.** Lint, type-checks, Vitest, and Cypress component tests all run in CI via `yarn test:all`. Keeping them green locally shortens review cycles.
+
+## Audience guide
+
+| Persona                        | Focus areas                                                                                                                          |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
+| Application consumers          | [getting-started.md](getting-started.md), [components.md](components.md), [theming.md](theming.md)                                   |
+| Component contributors         | [development-workflow.md](development-workflow.md), [components.md](components.md), [testing-and-quality.md](testing-and-quality.md) |
+| Release managers               | [release-management.md](release-management.md), [scripts-reference.md](scripts-reference.md)                                         |
+| QA and accessibility reviewers | [storybook.md](storybook.md), [testing-and-quality.md](testing-and-quality.md)                                                       |
+
+## Keeping this documentation healthy
+
+- Update the relevant guide whenever you add a notable script, workflow, or architectural rule.
+- Link to source files (`path/to/file.ts:Line`) when documenting opinions so readers can verify context quickly.
+- Prefer short, task-oriented sections rather than prose-heavy essays; readers should find answers in under a minute.
+- Raise a pull request for documentation gaps discovered during review and add them to [backlog.md](backlog.md) if they require separate follow-up.
+
+Questions or suggestions? Open a discussion in the repository or tag the design system maintainers in your pull request. This documentation is meant to evolve with the codebase.
diff --git a/docs/TODO.md b/docs/backlog.md
similarity index 100%
rename from docs/TODO.md
rename to docs/backlog.md
diff --git a/docs/components.md b/docs/components.md
new file mode 100644
index 00000000..f453b9c4
--- /dev/null
+++ b/docs/components.md
@@ -0,0 +1,133 @@
+# Components
+
+This guide explains how to consume, configure, and extend the Vue components provided by `@soramitsu-ui/ui`.
+
+## Import patterns
+
+### Global plugin
+
+The simplest way to register every component is through the bundled plugin. It installs components, composables, and global styles.
+
+```ts
+import { createApp } from 'vue'
+import { plugin as SoramitsuUI } from '@soramitsu-ui/ui'
+import '@soramitsu-ui/ui/styles'
+
+createApp(App).use(SoramitsuUI()).mount('#app')
+```
+
+Use this approach when you control the entire application shell and can tolerate the additional bundle size.
+
+### A-la-carte imports
+
+For micro-frontends or performance-sensitive builds, import only the pieces you need.
+
+```vue
+<script setup lang="ts">
+import { SButton, SAlert } from '@soramitsu-ui/ui'
+</script>
+
+<template>
+  <SAlert type="info">
+    <SButton appearance="secondary">Retry</SButton>
+  </SAlert>
+</template>
+```
+
+Tree shaking relies on ES module imports. Keep bundlers configured for ESM (`moduleResolution: "bundler"` in TypeScript, Vite build in ESM mode).
+
+### Styles
+
+All components share a single CSS bundle emitted as `@soramitsu-ui/ui/styles`. Import it once at the top of your project or in the plugin entry point. The CSS bundle injects CSS variables and resets sourced from `@soramitsu-ui/theme` tokens.
+
+## Component catalogue
+
+| Category   | Components                                                                             |
+| ---------- | -------------------------------------------------------------------------------------- |
+| Inputs     | `SCheckbox`, `SRadio`, `SSwitch`, `SSelect`, `STextField`, `SDatePicker`, `SJsonInput` |
+| Navigation | `SNavigationMenu`, `SNavigationSubmenu`, `SNavigationMenuItem`, `STabs`, `SLink`       |
+| Feedback   | `SAlert`, `SBadge`, `SProgressBar`, `SSpinner`, `SNotifications`, `SToasts`            |
+| Surfaces   | `SAccordion`, `SModal`, `SPopover`, `STable`, `SCard`-style layouts (table adapt mode) |
+| Utilities  | `SBodyScrollLockProvider`, `STooltip`, transition wrappers in `Transitions/`           |
+
+Storybook documents the full API surface with live examples. Use `yarn sb:serve` and navigate through component categories.
+
+## API conventions
+
+- **Props are typed via TypeScript interfaces** (`types.ts` per component). Keep props flat and serialisable; prefer objects for complex configuration.
+- **Events follow the `action:noun` pattern** (`click:row`, `update:modelValue`, `change:expand`). Avoid hyphenated legacy names when adding new events.
+- **Slots mirror the DOM structure** (e.g. `header`, `row`, `details`, `prefix`). When adding slots, document default renderers in the Storybook stories.
+- **Class names use BEM with underscores** (`button__icon_size_small`). Reuse existing modifiers before adding new ones.
+- **Accessibility first.** Components ship with ARIA attributes, focus management, and keyboard interactions. When editing them:
+  - Preserve tab order.
+  - Keep `aria-*` attributes in sync with state.
+  - Cover focus-trap behaviour in Cypress tests when toggling modals, popovers, and dropdowns.
+
+## Provide/inject contracts
+
+Complex components such as Checkbox groups, Navigation menus, and Tabs provide a context via `provide/inject`. Shared contracts live in `api.ts` inside the component directory. When extending APIs:
+
+1. Update the provided context type and default object.
+2. Consume the context via a dedicated composable (e.g. `useCheckboxGroupApi`).
+3. Document required provider usage in Storybook and this guide.
+
+## Data attributes for testing
+
+Cypress component tests target `data-testid` attributes. Keep them stable and descriptive:
+
+```vue
+<button data-testid="s-checkbox__control"> ... </button>
+```
+
+If you rename a `data-testid`, update the corresponding spec under `packages/ui/cypress/component/`.
+
+## Writing a new component
+
+1. **Scaffold the directory** under `packages/ui/src/components/<Name>` and create an `S<Name>.vue` file.
+2. **Export it** from `index.ts` inside the component folder, then surface it through `packages/ui/src/components/index.ts` and `all-components.ts`.
+3. **Author a Storybook story** in `packages/ui/stories/components/<Name>.stories.ts` to showcase common states, edge cases, and accessibility usage.
+4. **Write Cypress component tests** under `packages/ui/cypress/component/<Name>.spec.cy.ts`. Focus on keyboard interaction, focus traps, and visual state toggles.
+5. **Add unit tests** for complex utilities or composables in the component folder (`*.spec.ts`).
+6. **Lint and type-check** using `yarn lint:check` and `yarn --cwd packages/ui typecheck`.
+7. **Update API Extractor output** by running `yarn --cwd packages/ui build:tsc` followed by `yarn --cwd packages/ui api:extract:local`.
+
+## Composables and utilities
+
+`packages/ui/src/composables` and `packages/ui/src/util` host sharable logic such as:
+
+- `useClickOutside`
+- `useTrapFocus`
+- `useDimensions`
+- Date and formatting helpers
+
+When adding new composables:
+
+- Prefix the file with `use`.
+- Export both the named composable and the inferred return type.
+- Cover tricky logic with Vitest specs (`packages/ui/src/composables/__tests__`).
+- Document their intended use in component stories when they alter behaviour.
+
+## Icons
+
+The `icons` directory under the UI components is reserved for icon wrappers. Most implementations delegate to the `@soramitsu-ui/icons` package. When adding icons:
+
+- Add the SVG to `packages/icons` (if it does not exist yet).
+- Create a Vue wrapper in `packages/ui/src/components/icons` for consistent sizing and loading.
+- Update `packages/ui/src/components/icons/index.ts` to export new icons.
+
+## Accessibility checklist
+
+Before shipping a component change:
+
+- Verify keyboard navigation paths in Storybook.
+- Run Cypress specs with `yarn --cwd packages/ui cy:ci:component` (CI uses the same command).
+- Use `cypress-axe` or browser plugins to scan for WAI-ARIA violations.
+- Document accessible usage in the corresponding story (e.g. labelling inputs, describing popovers).
+
+## Integration tips
+
+- Keep consumer apps aligned with the same Vue version as listed in `packages/ui/package.json` (`^3.5.21`).
+- When using `pinia` or other peer dependencies in stories, import them inside Storybook preview files to avoid leaking peers into the component bundle.
+- For SSR projects, import CSS in the entry server file and avoid DOM-only APIs in component setup (gate them behind `if (process.client)` checks or use `onMounted`).
+
+Refer back to this guide whenever you introduce API changes to maintain consistency across the library.
diff --git a/docs/contributing.md b/docs/contributing.md
new file mode 100644
index 00000000..ddf513a8
--- /dev/null
+++ b/docs/contributing.md
@@ -0,0 +1,63 @@
+# Contributing
+
+We welcome contributions that enhance the Soramitsu UI library. This guide captures expectations for collaboration, code style, and review.
+
+## Communication
+
+- Discuss major features or breaking changes with maintainers before implementation.
+- Use GitHub issues for bugs and feature requests; cross-link related Storybook stories or Figma files.
+- Mention relevant stakeholders (design, QA) when changes impact them.
+
+## Coding standards
+
+- Follow the [components.md](components.md) conventions for Vue architecture, naming, and accessibility.
+- Adhere to the existing TypeScript config; avoid introducing alternative build systems without discussion.
+- Keep files ASCII-encoded unless existing files use extended characters.
+
+## Commit and Changeset messages
+
+- Commits can be descriptive (`fix: align tooltip with trigger`), but releases rely on Changesets for user-facing notes.
+- Changeset format: `**type**(scope): message` (e.g. `**fix**(SSelect): avoid double focus trap`).
+- Include breaking change notices in the Changeset body and in Storybook docs.
+
+## Documentation updates
+
+- Update this documentation suite whenever behaviour or workflows change.
+- Link to source files in doc updates (e.g. `packages/ui/src/components/Table/STable.vue:42`).
+- Keep Storybook stories in sync with component APIs.
+
+## Code review etiquette
+
+- Request review from at least one maintainer and one peer familiar with the affected area.
+- Provide context: describe motivation, highlight risky areas, attach screenshots or videos for visual tweaks.
+- Address review feedback promptly or start a discussion if trade-offs are involved.
+
+## Testing expectations
+
+- Run targeted tests locally; CI runs `yarn test:all`.
+- For UI behaviour changes, include or update Cypress specs.
+- Capture unusual failure cases in tests rather than comments.
+
+## Accessibility and internationalisation
+
+- Ensure keyboard navigation and focus order remain consistent.
+- Provide default English copy only when a string is essential; otherwise expose props/slots for localisation.
+- Use semantic HTML elements whenever possible.
+
+## Triaging issues
+
+- Confirm reported bugs by reproducing them in Storybook.
+- Label issues with affected components and severity.
+- Link to the relevant entry in [backlog.md](backlog.md) if it already tracks the gap.
+
+## Security
+
+- Do not include secrets in commits (API keys, tokens).
+- Report security concerns privately to the maintainers before opening public issues.
+
+## Contributor licence
+
+- Contributions are licensed under Apache 2.0, consistent with the repository licence.
+- Ensure third-party code complies with compatible licences before inclusion.
+
+Thank you for helping keep the Soramitsu design system robust and accessible. Raise a discussion if any part of this process can be improved—processes evolve alongside the codebase.
diff --git a/docs/development-workflow.md b/docs/development-workflow.md
new file mode 100644
index 00000000..d525275b
--- /dev/null
+++ b/docs/development-workflow.md
@@ -0,0 +1,90 @@
+# Development Workflow
+
+This guide captures the day-to-day routines for contributing to the Soramitsu UI monorepo.
+
+## Branch hygiene
+
+- Prefer `feat/<topic>`, `fix/<topic>`, or `chore/<topic>` naming.
+- Keep branches focused; split large features into incremental pull requests when possible.
+- Rebase onto the default branch before requesting review to avoid merge commits in history.
+
+## Editor setup
+
+- Enable ESLint and Prettier integration. For VS Code, install **Prettier ESLint** and configure "Format on Save" to call `./node_modules/.bin/prettier-eslint`.
+- Enable Volar or Vetur for Vue 3 single-file component support.
+- Configure TypeScript to use the workspace version (`cmd + shift + P` → "TypeScript: Select TypeScript Version" → "Use Workspace Version").
+
+## Local development loop
+
+1. **Install dependencies** (once per clone): `yarn`.
+2. **Run Storybook** when working on component visuals: `yarn sb:serve`.
+3. **Launch Vitest in watch mode** for instant feedback:
+   ```sh
+   yarn --cwd packages/ui test:unit --watch
+   ```
+4. **Start Cypress component tests** interactively if you change behaviour reliant on the DOM or keyboard interactions:
+   ```sh
+   yarn --cwd packages/ui cy
+   ```
+5. **Update theme builds** whenever you touch tokens: `yarn build:theme`.
+
+## Linting and formatting
+
+- Quick format fix: `yarn lint:format:fix`
+- ESLint only: `yarn lint:es`
+- Combined check (CI equivalent): `yarn lint:check`
+
+Ensure lint commands run clean before pushing. Prettier and ESLint rules are shared across packages to keep code style uniform.
+
+## Type checking
+
+Run type checks after significant TypeScript or Vue composable changes:
+
+```sh
+yarn --cwd packages/ui typecheck
+```
+
+CI runs this step implicitly via `yarn test:all`; catching issues locally speeds up review.
+
+## API Extractor updates
+
+When adding or modifying public component APIs:
+
+```sh
+yarn --cwd packages/ui build:tsc
+yarn --cwd packages/ui api:extract:local
+```
+
+Commit the resulting `ui.api.md` diff with the feature branch.
+
+## Storybook maintenance
+
+- Keep stories light; prefer controls over hard-coded variants.
+- Document breaking changes or new props through Storybook docs panels.
+- Run `yarn --cwd packages/ui sb:build` to ensure the static build passes before merging significant UI updates.
+
+## Changesets
+
+Every user-facing change (new component, breaking change, bug fix) should include a Changeset:
+
+```sh
+yarn changeset
+```
+
+Follow the prompt, using the `**type**(scope): message` format described in `README.md`.
+
+## Pull request checklist
+
+- [ ] Linting and formatting pass locally.
+- [ ] `yarn test:all` succeeds or any failing step is explained in the PR description.
+- [ ] Stories, tests, and docs updated alongside code changes.
+- [ ] API Extractor output updated when public APIs change.
+- [ ] Screenshots or GIFs attached for visual updates where helpful.
+
+## Reviewing others' work
+
+- Pull the branch locally when visual changes are involved; run Storybook to verify.
+- Check Cypress and Vitest snapshots for changes caused by the patch.
+- Cross-reference `backlog.md` to avoid regressing known gaps.
+
+Consistency and automation keep the design system reliable. Adapt this workflow as tooling evolves and document updates here.
diff --git a/docs/getting-started.md b/docs/getting-started.md
new file mode 100644
index 00000000..b70e05c9
--- /dev/null
+++ b/docs/getting-started.md
@@ -0,0 +1,118 @@
+# Getting Started
+
+Follow this guide to set up a local environment that can build, test, and publish Soramitsu UI packages. It covers both consumers (who install published packages) and contributors (who clone the monorepo).
+
+## Prerequisites
+
+- **Node.js 18 LTS or newer.** Earlier versions miss APIs used by Vite and Vitest. Verify with `node --version`.
+- **Yarn Classic (1.x).** The repository relies on workspaces; the `yarn.lock` is managed by Yarn 1. Install via `npm i -g yarn` if required.
+- **Git LFS** for large assets (optional today, but recommended for future design assets).
+- **Modern browser** (Chromium or Firefox) for Storybook and Cypress component testing.
+
+> Tip: Use [Volta](https://volta.sh/) or [nvm](https://github.com/nvm-sh/nvm) to pin Node versions per project.
+
+## Clone and install
+
+```sh
+# Clone the repository
+ git clone git@github.com:soramitsu/soramitsu-js-ui-library.git
+ cd soramitsu-js-ui-library
+
+# Install workspace dependencies
+ yarn
+```
+
+The install command resolves all workspace dependencies (including Storybook, Vite, Cypress, and token tooling). Expect the first install to take several minutes.
+
+## Bootstrap the toolchain
+
+Some workflows depend on generated artefacts:
+
+1. **Build the theme tokens at least once per session.**
+
+   ```sh
+   yarn build:theme
+   ```
+
+   This compiles Sass tokens into CSS variables consumed by the UI package.
+
+2. **Build the SVG plugin** (runs automatically before Storybook via `presb:serve`, but it can be invoked manually when testing changes to the plugin).
+
+   ```sh
+   yarn build:vite-plugin-svg
+   ```
+
+3. **Run Storybook** to explore components interactively.
+
+   ```sh
+   yarn sb:serve
+   ```
+
+   Storybook is served from `packages/ui/.storybook` and listens on port 6006 by default.
+
+4. **(Optional) Compile all packages.** Useful for ensuring release readiness.
+   ```sh
+   yarn build
+   ```
+
+## Working on a single package
+
+Each package ships with its own scripts and configuration located under `packages/<name>`.
+
+- **UI components:** `yarn --cwd packages/ui <script>`
+- **Theme tokens:** `yarn --cwd packages/theme <script>`
+- **SVG plugin:** `yarn --cwd packages/vite-plugin-svg <script>`
+- **Icons:** raw assets; no build step today.
+
+Example: run only the UI unit tests without touching other packages.
+
+```sh
+yarn --cwd packages/ui test:unit
+```
+
+## Linking the UI library into an application
+
+The published packages are available on NPM under the `@soramitsu-ui/*` scope. To develop against local builds:
+
+1. Build the UI package:
+   ```sh
+   yarn --cwd packages/ui build
+   ```
+2. From the root of the monorepo, create a link:
+   ```sh
+   yarn --cwd packages/ui link
+   ```
+3. In the consumer project:
+   ```sh
+   yarn link "@soramitsu-ui/ui"
+   yarn link "@soramitsu-ui/theme"   # if you need tokens locally
+   yarn link "@soramitsu-ui/vite-plugin-svg"  # optional, for local SVG fixes
+   ```
+4. Import the plugin in your Vue app:
+
+   ```ts
+   import { createApp } from 'vue'
+   import { plugin as SoramitsuPlugin } from '@soramitsu-ui/ui'
+
+   const app = createApp(App)
+   app.use(SoramitsuPlugin())
+   app.mount('#app')
+   ```
+
+Remember to unlink before installing from the registry to avoid mismatched dependency trees.
+
+## Verifying the installation
+
+Run the full project test suite to ensure your environment is ready:
+
+```sh
+yarn test:all
+```
+
+This command executes ESLint, Prettier checks, theme tests, Vitest unit suites, Cypress component tests, builds the SVG plugin, runs `build:theme`, executes the Vite build for the UI package, and finally runs post-build verification tests. Keep the output handy as a reference for what CI expects.
+
+## Next steps
+
+- Read [project-structure.md](project-structure.md) to understand where features live.
+- Visit [components.md](components.md) for usage patterns and API contracts.
+- Configure your editor and commit hooks following [development-workflow.md](development-workflow.md).
diff --git a/docs/glossary.md b/docs/glossary.md
new file mode 100644
index 00000000..883a4036
--- /dev/null
+++ b/docs/glossary.md
@@ -0,0 +1,21 @@
+# Glossary
+
+Shared vocabulary helps align discussions across design, engineering, and QA.
+
+- **A-la-carte import** — Importing individual components from `@soramitsu-ui/ui` instead of installing the full plugin. Optimises bundle size through tree shaking.
+- **Changeset** — Metadata describing a change that influences package version bumps and changelog generation. Created via `yarn changeset`.
+- **Design token** — Named design value (color, spacing, typography) that components consume. Managed in `@soramitsu-ui/theme`.
+- **Provide/inject** — Vue 3 dependency injection mechanism used to share context between parent and child components (e.g. checkbox group state).
+- **Storybook** — Interactive documentation site used to showcase and test components in isolation.
+- **Vitest** — Unit test runner configured for the UI package. Compatible with Jest expect assertions.
+- **Cypress component test** — E2E-style test mounting a component in isolation to assert UI interactions and accessibility.
+- **Windi CSS** — Utility-first CSS framework integrated with tokens for rapid layout prototyping.
+- **API Extractor** — Tool generating the `ui.api.md` report to track public TypeScript API changes.
+- **SVGO** — SVG optimiser used by the custom Vite plugin to transform icons into lightweight Vue components.
+- **Focus trap** — Behaviour that keeps keyboard focus inside modals/popovers; implemented via the `focus-trap` dependency.
+- **Data-testid** — Stable DOM attribute targeted by Cypress tests to avoid coupling to visual selectors.
+- **CI** — Continuous Integration pipeline that runs linting, tests, and builds (`yarn test:all`).
+- **Monorepo** — Single repository hosting multiple packages (icons, theme, UI, plugin) managed through Yarn workspaces.
+- **Storybook play function** — Async function attached to a story that performs interactions and assertions after the component renders.
+
+Add new entries as terminology evolves.
diff --git a/docs/project-structure.md b/docs/project-structure.md
new file mode 100644
index 00000000..72649769
--- /dev/null
+++ b/docs/project-structure.md
@@ -0,0 +1,77 @@
+# Project Structure
+
+The repository is a Yarn workspace monorepo. Each package owns its build tools, tests, and README, while shared automation lives at the root.
+
+```
+.
+├─ docs/                     # This documentation hub
+├─ package.json              # Workspace scripts and shared devDependencies
+├─ packages/
+│  ├─ icons/                 # Raw SVG icon assets
+│  ├─ theme/                 # Design tokens, typography, Sass helpers
+│  ├─ ui/                    # Vue 3 component library
+│  └─ vite-plugin-svg/       # Vite plugin used to import SVGs as Vue components
+├─ tsconfig.json             # Root TypeScript config (extends per-package configs)
+├─ lerna.json                # Release orchestration via Lerna
+└─ yarn.lock
+```
+
+## Root workspace
+
+- **`package.json`** exposes composite scripts (linting, test matrix, builds) and pins tool versions. Use it for cross-package tasks such as `yarn test:all` or `yarn build`.
+- **`tsconfig.json`** defines base compiler options used by package-level configs. Avoid editing it unless the change applies to every package.
+- **`lerna.json`** configures publishing behaviour. Releases rely on [release-management.md](release-management.md) plus Changesets metadata.
+- **`.github/`, CI, and Jenkins files** (if present) keep automation in sync with local scripts.
+
+## `packages/icons`
+
+- Contains only SVG files under directories such as `icomoon/`.
+- No build step; consumers import raw SVGs and process them with bundlers (see `packages/icons/README.md`).
+- Planned upgrades (tracked in [backlog.md](backlog.md)) include migrating to official Soramitsu icon sets.
+
+## `packages/theme`
+
+- Houses the Soramitsu design tokens and typography presets.
+- Key folders:
+  - `src/sass/` — token schema (`tokens.scss`), mixins, and typography definitions.
+  - `src/ts/` — TypeScript exports for token IDs and helpers.
+  - `scripts/` — build helpers (Rollup configs, token processors).
+  - `test/` — Jest tests validating token schemas and Sass utilities.
+- Builds generate `dist/` (bundled CSS/Sass) and `dist-ts/` (type declarations). See [theming.md](theming.md).
+
+## `packages/ui`
+
+- Vue 3 component library targeting Soramitsu-branded applications.
+- Key folders:
+  - `src/components/` — source for all components (Accordion, Alert, Button, Checkbox, DatePicker, etc.). Each component lives in its own directory with `S*.vue` files, composables, types, and constants.
+  - `src/composables/` — shared hooks (`useTeleport`, `useId`, etc.).
+  - `src/test-utils/` — helpers for Vitest and Cypress suites.
+  - `stories/` — Storybook stories grouped by component category.
+  - `cypress/` — component test specs and fixtures.
+  - `scripts/` — automation such as Storybook smoke test runner.
+  - `windi.config.ts` — Windi CSS configuration aligned with theme tokens.
+- Builds produce `dist/` (ESM, CJS, CSS) and `dist-ts/` (typed declarations).
+
+## `packages/vite-plugin-svg`
+
+- Lightweight fork of `vite-svg-loader` used by the UI package and Storybook.
+- Source lives under `src/`, compiled into `dist/` via `yarn --cwd packages/vite-plugin-svg build`.
+- Exposes minimal configuration (SVGO options). Documented in `packages/vite-plugin-svg/README.md`.
+
+## Additional tooling
+
+- **`next.Dockerfile` / `next.Jenkinsfile`** — CI/CD templates for building Storybook previews and running the full pipeline.
+- **`packages/ui/vite.config.mts`** — Vite bundler configuration for packaging components and Storybook.
+- **`packages/ui/api-extractor.json`** — API Extractor configuration for generating `ui.api.md`.
+
+## Where to place new work
+
+| Task                         | Location                                                    | Notes                                                                                   |
+| ---------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| New Vue component            | `packages/ui/src/components/<Name>`                         | Export via `index.ts` and `all-components.ts`; add Storybook stories and Cypress tests. |
+| Shared composable            | `packages/ui/src/composables`                               | Prefix with `use` and document in [components.md](components.md).                       |
+| Token or typography addition | `packages/theme/src/sass/tokens.scss` and related utilities | Update docs in [theming.md](theming.md) and add Jest coverage.                          |
+| Storybook configuration      | `packages/ui/.storybook` and `stories/`                     | Story-level guidance in [storybook.md](storybook.md).                                   |
+| Release automation           | Root scripts or `lerna.json`                                | Coordinate with [release-management.md](release-management.md).                         |
+
+Keeping this structure predictable simplifies navigation for both designers and engineers. If you introduce a new folder or package, document it here.
diff --git a/docs/release-management.md b/docs/release-management.md
new file mode 100644
index 00000000..c44cd3d6
--- /dev/null
+++ b/docs/release-management.md
@@ -0,0 +1,85 @@
+# Release Management
+
+This document explains how to promote local changes into published packages under the `@soramitsu-ui/*` scope.
+
+## Prerequisites
+
+- Access to the Soramitsu NPM organisation with publish permissions.
+- Git credentials capable of creating release branches and tags.
+- Clean working tree: `git status` should report no pending changes (run `yarn test:all` first).
+
+## Versioning workflow
+
+1. **Ensure every change has a Changeset.** Use `yarn changeset` when merging feature branches.
+2. **Create a release branch** (e.g. `release/ui-0.9.0`).
+3. **Apply version bumps**:
+   ```sh
+   yarn changeset version
+   ```
+   This updates package versions and generates changelog entries in each package.
+4. **Install dependencies** to refresh the lockfile:
+   ```sh
+   yarn
+   ```
+5. **Review changelog diffs** for clarity and adjust wording if necessary.
+
+## Validation matrix
+
+Before publishing, run:
+
+```sh
+yarn test:all
+```
+
+Optionally, run targeted checks if only certain packages changed:
+
+- Theme only: `yarn --cwd packages/theme test`
+- UI package only: `yarn --cwd packages/ui build` and `yarn --cwd packages/ui test:unit`
+- Storybook: `yarn --cwd packages/ui sb:build`
+
+## Publishing
+
+Once the release branch passes QA:
+
+1. **Merge the release branch** into the default branch via pull request.
+2. **Tag the release** (optional, but recommended): `git tag ui-v0.9.0 && git push origin ui-v0.9.0`.
+3. **Publish packages** to NPM:
+   ```sh
+   yarn publish-workspaces
+   ```
+   This runs `lerna publish from-package`, pushing already versioned packages to the registry.
+4. **Verify on NPM** that the packages (`@soramitsu-ui/ui`, `@soramitsu-ui/theme`, `@soramitsu-ui/vite-plugin-svg`, `@soramitsu-ui/icons`) list the new versions.
+
+## Post-release tasks
+
+- Announce the release in the team channel with highlights from the changelog.
+- Update downstream applications if they rely on the new build.
+- Close or update issues linked to the release milestone.
+
+## Hotfixes
+
+1. Branch from the latest release tag (`git checkout -b hotfix/ui-0.8.1 ui-v0.8.0`).
+2. Cherry-pick or apply the fix.
+3. Run `yarn changeset` with the `patch` option.
+4. Follow the same release flow with a patch version increment.
+
+## Deprecation policy
+
+- Mark deprecated APIs in code comments and Storybook docs.
+- Reference the deprecation and planned removal version in the changelog.
+- Provide migration tips in [components.md](components.md) or dedicated upgrade guides.
+
+## Coordinating multiple packages
+
+When a change spans theme and UI packages:
+
+- Ensure the theme publishes first, or use a single release branch covering both packages.
+- Update peer dependency ranges if the theme introduces breaking changes consumed by the UI package.
+- Communicate sequencing in the release announcement.
+
+## Jenkins / CI pipelines
+
+- `next.Jenkinsfile` outlines the CI stages. Keep it in sync with new scripts or job requirements.
+- Docker builds rely on `next.Dockerfile`. Rebuild the base image when adding runtime dependencies (e.g. new system packages required by Storybook).
+
+Maintain this document as processes evolve (e.g. moving to automated publishing, adding canary releases, or integrating provenance signatures).
diff --git a/docs/scripts-reference.md b/docs/scripts-reference.md
new file mode 100644
index 00000000..7fd352b5
--- /dev/null
+++ b/docs/scripts-reference.md
@@ -0,0 +1,74 @@
+# Scripts Reference
+
+Use this cheat sheet to find the right Yarn script for each task. Run commands from the repository root unless noted otherwise.
+
+## Root-level scripts
+
+| Command                      | Purpose                                                                                |
+| ---------------------------- | -------------------------------------------------------------------------------------- |
+| `yarn build`                 | Builds theme, SVG plugin, and UI package in sequence.                                  |
+| `yarn build:theme`           | Compiles design tokens and typography assets.                                          |
+| `yarn build:vite-plugin-svg` | Builds the custom SVG loader used by Storybook and the UI package.                     |
+| `yarn build:ui`              | Runs the full UI build (`clean` → `tsc` → `vite` → `api:extract`).                     |
+| `yarn build:ui:only-vite`    | Executes only the Vite bundle step for the UI package.                                 |
+| `yarn sb:serve`              | Starts Storybook on port 6006 (prebuilds the SVG plugin).                              |
+| `yarn sb:build`              | Produces a static Storybook build under `packages/ui/storybook-static`.                |
+| `yarn test:all`              | Full quality gate: lint → tests → builds. Mirrors CI.                                  |
+| `yarn test:theme:unit`       | Runs Jest suites for `@soramitsu-ui/theme`.                                            |
+| `yarn test:ui:unit`          | Executes Vitest unit tests for the UI package.                                         |
+| `yarn test:ui:cy`            | Runs Cypress component tests in headless mode.                                         |
+| `yarn test:ui:cy-open`       | Opens the interactive Cypress runner.                                                  |
+| `yarn test:ui:after-build`   | Post-build verification for compiled UI output.                                        |
+| `yarn lint:es`               | Runs ESLint across the workspace.                                                      |
+| `yarn lint:es:fix`           | Runs ESLint with auto-fix.                                                             |
+| `yarn lint:format:check`     | Checks Prettier formatting.                                                            |
+| `yarn lint:format:fix`       | Applies Prettier formatting, then ESLint auto-fix.                                     |
+| `yarn lint:check`            | Executes `lint:es` and `lint:format:check`.                                            |
+| `yarn storybook:verify`      | Ensures Storybook builds cleanly (prebuilds the SVG plugin automatically).             |
+| `yarn publish-workspaces`    | Publishes all packages that have been versioned via Changesets (Lerna `from-package`). |
+
+## Package-specific scripts
+
+### `packages/ui`
+
+Run with `yarn --cwd packages/ui <script>`.
+
+| Script              | Purpose                                                        |
+| ------------------- | -------------------------------------------------------------- |
+| `build`             | Clean, type-check, Vite build, API Extractor.                  |
+| `build:clean`       | Removes `dist/` and `dist-ts/`.                                |
+| `build:tsc`         | Generates type declarations via `vue-tsc`.                     |
+| `build:vite`        | Bundles the library using Vite (ESM + CJS outputs).            |
+| `api:extract`       | Produces `ui.api.md` using Microsoft API Extractor.            |
+| `api:extract:local` | API Extractor in local mode (skips .api.md consistency check). |
+| `sb:serve`          | Storybook dev server scoped to the UI package.                 |
+| `sb:build`          | Storybook static export.                                       |
+| `sb:test`           | Runs Storybook test runner (Playwright).                       |
+| `test:unit`         | Vitest unit tests.                                             |
+| `test:after-build`  | Runs assertions against the compiled `dist/`.                  |
+| `cy`                | Opens Cypress component UI runner.                             |
+| `cy:ci:component`   | Headless Cypress component tests.                              |
+| `typecheck`         | TypeScript type checking via `vue-tsc`.                        |
+
+### `packages/theme`
+
+Run with `yarn --cwd packages/theme <script>`.
+
+| Script  | Purpose                                                   |
+| ------- | --------------------------------------------------------- |
+| `build` | Compiles Sass tokens and TypeScript exports into `dist/`. |
+| `test`  | Jest suite validating token schemas and mixins.           |
+
+### `packages/vite-plugin-svg`
+
+Run with `yarn --cwd packages/vite-plugin-svg <script>`.
+
+| Script  | Purpose                              |
+| ------- | ------------------------------------ |
+| `build` | Bundles the plugin for distribution. |
+
+### `packages/icons`
+
+No scripts today (raw SVG assets only). Use bundler-specific loaders when consuming the package.
+
+Keep this table updated as new automation lands in `package.json` files.
diff --git a/docs/storybook.md b/docs/storybook.md
new file mode 100644
index 00000000..d6832111
--- /dev/null
+++ b/docs/storybook.md
@@ -0,0 +1,120 @@
+# Storybook Guide
+
+Storybook is the living documentation for Soramitsu UI components. It doubles as a playground for designers, engineers, and QA.
+
+## Running Storybook
+
+```sh
+yarn sb:serve
+```
+
+- Serves `packages/ui/.storybook` on http://localhost:6006.
+- Automatically rebuilds when Vue components or stories change.
+- Uses the local build of `@soramitsu-ui/vite-plugin-svg`; ensure `yarn build:vite-plugin-svg` succeeds beforehand (scripts trigger it automatically).
+
+To produce a static build:
+
+```sh
+yarn --cwd packages/ui sb:build
+```
+
+Static exports are written to `packages/ui/storybook-static` and can be deployed to static hosting or served in CI previews.
+
+## Project configuration
+
+Storybook configuration resides in `packages/ui/.storybook`:
+
+- `main.ts` — story entry globs, addons (actions, controls, docs, accessibility), builder configuration.
+- `preview.ts` — global decorators, theming, testing utilities, and parameter defaults.
+- `manager.ts` (optional) — UI theming for the Storybook chrome.
+
+Adjust these files when adding addons, tweaking Vite settings, or altering the story hierarchy.
+
+## Authoring stories
+
+Story files live under `packages/ui/stories` and follow the `.stories.ts` convention.
+
+Guidelines:
+
+- Export a `default` metadata object with `title`, `component`, and `argTypes` for controls.
+- Use CSF 3 syntax (functions returning template objects) to maximise compatibility with Storybook Docs.
+- Provide meaningful default args that mirror real-world usage.
+- Showcase edge cases (empty states, long labels, loading) alongside primary variants.
+- Leverage `play` functions for interactive demos or accessibility assertions.
+
+Example skeleton:
+
+```ts
+import type { Meta, StoryObj } from '@storybook/vue3'
+import { SButton } from '@soramitsu-ui/ui'
+
+const meta: Meta = {
+  title: 'Components/Button',
+  component: SButton,
+  args: {
+    appearance: 'primary',
+    disabled: false,
+  },
+}
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Primary: Story = {
+  args: {
+    label: 'Submit',
+  },
+}
+```
+
+## Controls and documentation
+
+- Use `argTypes` to expose props and events via Storybook Controls.
+- Document slots using `parameters.docs.source` or MDX docs pages if additional explanation is required.
+- Provide annotations for keyboard shortcuts and ARIA usage.
+
+## Accessibility testing
+
+- Enable the `@storybook/addon-a11y` panel to audit each story.
+- For complex components (modals, popovers), add `play` functions that run `axe` checks:
+
+  ```ts
+  import { within, userEvent } from '@storybook/testing-library'
+  import { expect } from '@storybook/jest'
+
+  export const WithA11y: Story = {
+    play: async ({ canvasElement }) => {
+      const canvas = within(canvasElement)
+      const trigger = await canvas.findByRole('button')
+      await userEvent.click(trigger)
+      await expect(await axe(canvasElement)).toHaveNoViolations()
+    },
+  }
+  ```
+
+## Story naming conventions
+
+- Group stories by domain: `Components/Button`, `Feedback/Alert`, `Navigation/Tabs`.
+- Use `Docs` stories to provide long-form explanations or migration notes.
+- Keep story IDs stable; renaming titles will break deep links shared with designers or QA.
+
+## Integrating design resources
+
+- Embed Figma links in docs panels for design parity.
+- Use `parameters.backgrounds` to demonstrate behaviour on brand colours or dark mode.
+- Provide `parameters.design` (via addon) when referencing specific mockups.
+
+## Continuous integration
+
+- `yarn --cwd packages/ui sb:test` runs Storybook test runner via Playwright. Add bespoke assertions for mission-critical stories.
+- Consider adding visual regression tooling (Chromatic, Percy) by wiring it into the build output (`storybook-static`). Document steps here once adopted.
+
+## Troubleshooting
+
+| Symptom                                | Fix                                                                                                  |
+| -------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| Storybook fails with SVG import errors | Rebuild the SVG plugin (`yarn build:vite-plugin-svg`) or reinstall dependencies.                     |
+| Stories render blank                   | Inspect console for missing theme CSS. Ensure `@soramitsu-ui/ui/styles` is imported in `preview.ts`. |
+| Controls panel missing props           | Export prop typings or ensure `defineProps` includes default values for Storybook to infer.          |
+
+Keep this guide updated as Storybook evolves (new addons, frameworks, or CI integrations).
diff --git a/docs/testing-and-quality.md b/docs/testing-and-quality.md
new file mode 100644
index 00000000..f60043dd
--- /dev/null
+++ b/docs/testing-and-quality.md
@@ -0,0 +1,85 @@
+# Testing and Quality
+
+Quality gates protect the component library from regressions. This guide covers the available checks and how to run them efficiently.
+
+## CI equivalent: `yarn test:all`
+
+The root script orchestrates the entire matrix:
+
+1. `lint:check` → ESLint plus Prettier diff mode.
+2. `test:theme:unit` → Jest tests for the theme package.
+3. `build:vite-plugin-svg` → Ensures the SVG loader compiles.
+4. `test:ui:unit` → Vitest suites for UI utilities and Vue components.
+5. `build:theme` → Rebuilds token artefacts.
+6. `test:ui:cy` → Cypress component tests in headless mode.
+7. `build:ui:only-vite` → Production Vite build of the UI package.
+8. `test:ui:after-build` → Vitest assertions verifying compiled output.
+
+Keep the order intact when editing scripts; later steps assume earlier ones succeeded.
+
+## Static analysis
+
+- **ESLint (`yarn lint:es`)** — Vue, TypeScript, and accessibility rules.
+- **Prettier (`yarn lint:format:check`)** — Ensures consistent formatting.
+- **TypeScript (`yarn --cwd packages/ui typecheck`)** — Fails on type regressions missed by Vue SFC inference.
+
+Integrate ESLint and TypeScript into IDEs to catch issues before commits.
+
+## Unit testing with Vitest
+
+- Command: `yarn --cwd packages/ui test:unit`
+- Uses `happy-dom` for DOM emulation.
+- Test files typically live beside the code (`*.spec.ts`).
+- Prefer testing composables and pure utilities at this layer. For visual regressions, rely on Storybook and Cypress.
+- Run in watch mode (`--watch`) during development.
+
+## Theme tests with Jest
+
+`packages/theme/test` contains Jest suites that validate token schemas, Sass utilities, and preset generation. Always run `yarn --cwd packages/theme test` after touching theme Sass or scripts.
+
+## Cypress component testing
+
+- Interactive mode: `yarn --cwd packages/ui cy`
+- Headless CI mode: `yarn --cwd packages/ui cy:ci:component`
+- Specs live under `packages/ui/cypress/component/`.
+- Tests mount Vue components in isolation, asserting focus management, popover positioning, and keyboard interaction.
+- Accessibility checks leverage `cypress-axe`; ensure new components include `axe` scans in their specs when relevant.
+
+### Troubleshooting Cypress
+
+- Delete cached builds (`yarn --cwd packages/ui build:clean`) if stories stop mounting.
+- Use `CYPRESS_BASE_URL=http://localhost:6006` when pointing tests at a running Storybook instance.
+
+## Storybook verification
+
+- Static build: `yarn --cwd packages/ui sb:build`
+- Smoke test script: `yarn --cwd packages/ui sb:test` (wraps Storybook test runner via Playwright).
+- Keep stories deterministic; avoid random data that breaks snapshots or Playwright assertions.
+
+## Accessibility and visual QA
+
+- Leverage Storybook's accessibility addon for quick ARIA audits.
+- Use Percy, Chromatic, or Mirage (if available) to capture visual diffs. Integrations can be added to `.storybook/main.ts` as needed.
+- Document accessibility considerations in stories and component docs.
+
+## Performance checks
+
+- Run `yarn --cwd packages/ui build:vite` and inspect bundle analyzer output (enable via Vite plugin if not already).
+- Monitor `sideEffects` declarations in `package.json` to keep tree shaking effective.
+
+## Adding new tests
+
+1. Identify the appropriate layer (unit vs. component vs. integration).
+2. Locate the existing folder (e.g. `packages/ui/src/components/Button/__tests__`).
+3. Write deterministic tests that assert behaviour, not implementation details.
+4. Update this file if you introduce new testing conventions or tooling.
+
+## Reporting failures
+
+When a check fails in CI:
+
+- Re-run the corresponding script locally.
+- Attach logs or screenshots to the pull request.
+- Open an issue if the failure stems from flaky infrastructure rather than code changes.
+
+Maintaining a fast, reliable test matrix keeps the design system trustworthy. Evolve this guide as you adopt new tooling (e.g. Storybook test runner, visual diff services).
diff --git a/docs/theming.md b/docs/theming.md
new file mode 100644
index 00000000..83c85937
--- /dev/null
+++ b/docs/theming.md
@@ -0,0 +1,137 @@
+# Theming and Design Tokens
+
+The Soramitsu design system revolves around reusable **tokens** (color, spacing, typography, motion) and **typography presets** compiled in the `@soramitsu-ui/theme` package. Components in `@soramitsu-ui/ui` read from these tokens to stay visually consistent.
+
+## Token taxonomy
+
+Tokens are grouped by abstraction level:
+
+- `ref` — universal references (base palette, font families, radii).
+- `sys` — system-level choices derived from references (primary button background, success state colors).
+- `comp` — component-specific overrides required for bespoke UI parts.
+
+The hierarchy flows from `ref` → `sys` → `comp`. Higher layers should not depend on lower-level variables.
+
+Token definitions live in `packages/theme/src/sass/tokens.scss`. Each entry describes the schema, which Sass utilities expand into CSS Custom Properties using the `--sora_<path>` naming pattern.
+
+## Sass utilities
+
+Import the Sass module and use the provided mixins/functions to bind or evaluate tokens:
+
+```scss
+@use '@soramitsu-ui/fonts/Sora';
+@use '@soramitsu-ui/theme/sass' as theme;
+
+@include theme.typography-preset-default;
+
+:root {
+  // Bind full preset values
+  @include theme.tokens-preset-light;
+
+  // Override specific values
+  @include theme.eval-tokens-partial(
+    (
+      sys: (
+        color: (
+          primary: #0057b8,
+        ),
+      ),
+    )
+  );
+}
+
+.button {
+  color: theme.token-as-var('sys.color.on-primary');
+}
+```
+
+- `token()` returns the raw CSS variable name.
+- `token-as-var()` wraps the variable in `var(...)`.
+- `eval-tokens()` and `eval-tokens-partial()` assign concrete values to token paths.
+
+Typography presets (mixins prefixed with `typography-preset-`) emit utility classes like `.sora-tpg-h1` and `.sora-tpg-body`.
+
+## Runtime theming
+
+Components rely on CSS variables, making runtime theme switches straightforward:
+
+1. Include both base and dark/light overrides in your bundle.
+2. Toggle a class on the root element that scopes the overrides.
+
+```scss
+:root {
+  @include theme.tokens-preset-light;
+}
+
+[data-theme='dark'] {
+  @include theme.tokens-preset-dark;
+}
+```
+
+```ts
+const toggleTheme = (isDark: boolean) => {
+  document.documentElement.dataset.theme = isDark ? 'dark' : 'light'
+}
+```
+
+Avoid re-importing Sass at runtime; generate the CSS once during build.
+
+## Consuming tokens in Vue components
+
+- Prefer CSS variables over hard-coded values inside `.vue` files.
+- Use `@soramitsu-ui/ui/theme` utility files when available (e.g. helpers translating token IDs to class names).
+- For dynamic styles, bind inline styles to the CSS variable: `:style="{ backgroundColor: 'var(--sora_sys_color_primary)' }"`.
+
+## JavaScript token schema
+
+The theme package exports the token identifier list for type-safe lookups:
+
+```ts
+import { themeTokenIds, ThemeTokenId } from '@soramitsu-ui/theme'
+
+const primaryColor: ThemeTokenId = themeTokenIds.find((id) => id.includes('primary'))
+```
+
+Use these helpers when building tooling (e.g. docs, design token browsers) to avoid typo-prone string literals.
+
+## Windi CSS integration
+
+Windi CSS is configured in `packages/ui/windi.config.ts` to bridge tokens with utility classes. When adding tokens that should become utility classes:
+
+1. Extend the Windi config with new `theme.extend` entries referencing token variables.
+2. Regenerate the theme build (`yarn build:theme`).
+3. Validate in Storybook and Cypress to ensure utilities resolve correctly.
+
+## Updating tokens
+
+1. Edit the schema in `packages/theme/src/sass/tokens.scss`.
+2. Adjust corresponding preset files (e.g. `tokens-preset-light.scss`).
+3. Run the theme tests:
+   ```sh
+   yarn --cwd packages/theme test
+   ```
+4. Rebuild the theme:
+   ```sh
+   yarn build:theme
+   ```
+5. Document the change in [theming.md](theming.md) (this file) or link to the changelog.
+6. If the change affects component visuals, update screenshots, stories, and release notes.
+
+## Fonts
+
+Typography mixins rely on the Sora font available via `@soramitsu-ui/fonts`. Import the font package at the application entry point or include it through your asset pipeline. Ensure `font-display: swap` is enabled to avoid blocking render.
+
+## Icons and theme
+
+Icon colors derive from `sys.color` tokens by default. When overriding icon themes:
+
+- Use currentColor-friendly SVGs so they honour surrounding text color.
+- Inject component-specific colors through CSS variables rather than static fills.
+
+## Reference material
+
+- `packages/theme/README.md` — canonical reference for Sass utilities.
+- Material Design 3 token primer (https://m3.material.io/foundations/design-tokens/overview) — conceptual background.
+- [components.md](components.md) — demonstrates how tokens flow into component APIs.
+
+Document new token categories or deprecations here whenever you evolve the design system.
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
new file mode 100644
index 00000000..edc9a737
--- /dev/null
+++ b/docs/troubleshooting.md
@@ -0,0 +1,56 @@
+# Troubleshooting
+
+This page lists common issues encountered while working with the Soramitsu UI monorepo and how to resolve them.
+
+## Installation issues
+
+| Symptom                                  | Resolution                                                                                          |
+| ---------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `node` version mismatch errors           | Install Node 18+ and clear `node_modules` (`rm -rf node_modules && yarn`).                          |
+| Yarn complains about incompatible engine | Ensure you are using Yarn 1.x (`yarn --version`). Remove `.pnp.cjs` if Yarn 2+ was previously used. |
+| `esbuild` download failures              | Set the `ESBUILD_BINARY_PATH` or install via `yarn add --dev esbuild` manually, then retry `yarn`.  |
+
+## Storybook fails to start
+
+- Rebuild the SVG plugin: `yarn build:vite-plugin-svg`.
+- Delete Storybook cache: `rm -rf node_modules/.cache/storybook`.
+- Confirm no other process is bound to port 6006.
+
+## Cypress tests fail locally
+
+- Ensure Storybook or dev server is not already using the port Cypress expects.
+- Run in headed mode (`yarn --cwd packages/ui cy`) to observe interactions.
+- If tests hang on mount, clear Vite caches: `rm -rf packages/ui/node_modules/.vite`.
+
+## Vitest cannot find Vue types
+
+- Open VS Code command palette and select "TypeScript: Select TypeScript Version" → "Use Workspace Version".
+- Run `yarn --cwd packages/ui typecheck` to surface missing dependency hints.
+
+## Build errors referencing theme tokens
+
+- Run `yarn build:theme` to regenerate CSS and TS outputs.
+- Inspect `packages/theme/src/sass/tokens.scss` for typos; Sass will throw detailed location info.
+- Confirm consuming components import the correct Sass entry point.
+
+## API Extractor failures
+
+- Delete `packages/ui/dist-ts` and rerun `yarn --cwd packages/ui build:tsc`.
+- Ensure any new types are exported from their `index.ts` barrel before running `api:extract`.
+
+## `focus-trap` or DOM-specific errors during SSR builds
+
+- Guard DOM usage with `if (typeof window !== 'undefined')` checks or move logic to `onMounted` hooks.
+- Provide no-op fallbacks when running on the server.
+
+## Lerna publish issues
+
+- Verify you are logged into the NPM registry (`npm whoami`).
+- If publishing fails mid-way, reset the git tag if created locally and retry after resolving the root cause.
+
+## Editor-specific quirks
+
+- Volar auto-imports may point to `dist/` files. Prefer source imports during development and rely on bundlers for path resolution.
+- When using WebStorm, mark `packages/*/dist` directories as excluded to prevent indexing overhead.
+
+If you encounter an issue not listed here, document the fix in this file so future contributors can benefit.
diff --git a/packages/ui/src/components/Alert/SAlert.vue b/packages/ui/src/components/Alert/SAlert.vue
index 950a2911..d5ca93d7 100644
--- a/packages/ui/src/components/Alert/SAlert.vue
+++ b/packages/ui/src/components/Alert/SAlert.vue
@@ -88,7 +88,7 @@ function onClickClose() {
     }
   }
 
-  // TODO(see docs/TODO.md#alert) implement inline variant
+  // TODO(see docs/backlog.md#alert) implement inline variant
 
   &__icon-wrapper svg,
   &__close-wrapper svg {
diff --git a/packages/ui/src/components/Popover/util.ts b/packages/ui/src/components/Popover/util.ts
index ab3d2ee5..091545df 100644
--- a/packages/ui/src/components/Popover/util.ts
+++ b/packages/ui/src/components/Popover/util.ts
@@ -1,7 +1,7 @@
 import type { Ref, BaseTransitionProps } from 'vue'
 
 /**
- * TODO(see docs/TODO.md#popover) Reuse this functionality in `SModal` to remove duplication.
+ * TODO(see docs/backlog.md#popover) Reuse this functionality in `SModal` to remove duplication.
  */
 export function useWrappedTransitionVisibility({ show, eager }: { show: Ref<boolean>; eager: Ref<boolean> }): {
   wrapperIf: Ref<boolean>
diff --git a/packages/ui/src/components/Select/SSelectBase.vue b/packages/ui/src/components/Select/SSelectBase.vue
index 6d6c28e5..0bd2f949 100644
--- a/packages/ui/src/components/Select/SSelectBase.vue
+++ b/packages/ui/src/components/Select/SSelectBase.vue
@@ -25,12 +25,12 @@ const props = withDefaults(
     /**
      * - Doesn't allow to unselect value in single mode
      * - Doesn't allow to unselect last the only one picked value in multiple mode
-     * - Planned: auto-selects the first available option when `modelValue` is null (see docs/TODO.md#select)
+     * - Planned: auto-selects the first available option when `modelValue` is null (see docs/backlog.md#select)
      */
     mandatory?: boolean
 
     /**
-     * Planned: synchronize dropdown width with trigger width (see docs/TODO.md#select)
+     * Planned: synchronize dropdown width with trigger width (see docs/backlog.md#select)
      */
     syncMenuAndInputWidths?: boolean
 
diff --git a/packages/ui/src/components/Select/types.ts b/packages/ui/src/components/Select/types.ts
index e98ca0f7..55d0b33e 100644
--- a/packages/ui/src/components/Select/types.ts
+++ b/packages/ui/src/components/Select/types.ts
@@ -10,7 +10,7 @@ export type SelectSize = typeof SelectSize[keyof typeof SelectSize]
 export const SelectButtonType = {
   Default: 'default',
   Inline: 'inline',
-  // TODO(see docs/TODO.md#select) append icon-only variant once design is ready
+  // TODO(see docs/backlog.md#select) append icon-only variant once design is ready
   // Icon = 'icon'
 } as const
 
diff --git a/packages/ui/src/components/Spinner/SSpinner.vue b/packages/ui/src/components/Spinner/SSpinner.vue
index 125b764e..c0bb5826 100644
--- a/packages/ui/src/components/Spinner/SSpinner.vue
+++ b/packages/ui/src/components/Spinner/SSpinner.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 // Animated SVG comes from https://codepen.io/supah/pen/BjYLdW
-// TODO(see docs/TODO.md#spinner) refactor to a functional component to avoid runtime overhead
+// TODO(see docs/backlog.md#spinner) refactor to a functional component to avoid runtime overhead
 
 interface Props {
   /**
diff --git a/packages/ui/src/components/Table/STable.vue b/packages/ui/src/components/Table/STable.vue
index de526f7b..e347cb2a 100644
--- a/packages/ui/src/components/Table/STable.vue
+++ b/packages/ui/src/components/Table/STable.vue
@@ -134,7 +134,7 @@ const props = withDefaults(
      * */
     expandRowKeys?: unknown[]
 
-    /** TODO(see docs/TODO.md#table): integrate shared tooltip helper once available */
+    /** TODO(see docs/backlog.md#table): integrate shared tooltip helper once available */
     // tooltipEffect: 'dark' | 'light'
 
     /**
diff --git a/packages/ui/src/components/icons/index.ts b/packages/ui/src/components/icons/index.ts
index b807dbad..99598d66 100644
--- a/packages/ui/src/components/icons/index.ts
+++ b/packages/ui/src/components/icons/index.ts
@@ -29,7 +29,7 @@ import IconChevronsLeft16 from '@soramitsu-ui/icons/icomoon/chevrons-left-16.svg
 // import IconBasicEye24 from '@soramitsu-ui/icons/icomoon/basic-eye-24.svg'
 // import IconBasicEyeNo24 from '@soramitsu-ui/icons/icomoon/basic-eye-no-24.svg'
 
-// TODO(see docs/TODO.md#icons) update design system once official assets arrive
+// TODO(see docs/backlog.md#icons) update design system once official assets arrive
 import IconEye from '~icons/majesticons/eye-line'
 import IconEyeOff from '~icons/majesticons/eye-off-line'
 
@@ -83,7 +83,7 @@ export const STATUS_ICONS_MAP: { [K in Status]: Component } = {
 }
 
 /**
- * TODO(see docs/TODO.md#icons) append info icon once supplied; STextField currently doesn’t
+ * TODO(see docs/backlog.md#icons) append info icon once supplied; STextField currently doesn’t
  * need "info" entry here
  */
 export const STATUS_ICONS_MAP_16: { [K in Exclude<Status, typeof Status.Info>]: Component } = {