soramitsu · takemiyamakoto · Sep 29, 2025 · May 31, 2021 · Jun 1, 2021 · Jun 2, 2021
diff --git 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
@@ -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 → docs/backlog.md b/docs/TODO.md → docs/backlog.md
diff --git a/docs/components.md 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
@@ -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
@@ -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.