From 3f85860f8396adb7b55251da0c679a36fb83af89 Mon Sep 17 00:00:00 2001
From: topsinoty <topsinoty@gmail.com>
Date: Sat, 4 Jul 2026 15:55:55 +0300
Subject: [PATCH] docs(readme): document Vue setup and project structure

Replace the Svelte badge and stale runtime references with the Vue 3 toolchain, current Node requirement, and reproducible npm ci installation path.

Tell the contributor story from entry point to page: explain how App.vue, the custom router, bilingual routes, shared components, locale JSON, YAML content, public assets, and Vue Storybook fit together, then list the commands used for local development and verification.

Update the component guide for Vue props, slots, layout primitives, Svg.vue variants, and Storybook controls so contributors can find the right abstraction before adding route-specific markup.
---
 README.md                | 37 ++++++++++++++++++++++++++++++++-----
 src/components/README.md | 12 ++++++------
 2 files changed, 38 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index f0023ae..2a3661e 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # Lapikud External Website
 
-![Built with Svelte](https://img.shields.io/badge/Svelte-5-FF3E00?logo=svelte&logoColor=white)
+![Built with Vue](https://img.shields.io/badge/Vue-3-42B883?logo=vuedotjs&logoColor=white)
 ![Built with Vite](https://img.shields.io/badge/Vite-646CFF?logo=vite&logoColor=white)
 ![Deployed on GitHub Pages](https://img.shields.io/badge/Deployed-GitHub%20Pages-222?logo=github)
 
@@ -28,7 +28,7 @@ Found a bug, typo, or something missing? [Open an issue](https://github.com/Lapi
 
 ### What you need first
 
-- [Node.js](https://nodejs.org/) — v18 or higher, but grab the **LTS version** (currently v24) to be safe
+- [Node.js](https://nodejs.org/) — v20.19 or higher; use the current **LTS version** when possible
 
 > Node.js comes with `npm` included, so you don't need to install that separately.
 
@@ -77,10 +77,10 @@ git clone https://github.com/Lapikud/lapikud.github.io.git
 cd lapikud.github.io
 ```
 
-**2. Install dependencies** — this installs all the packages the project needs:
+**2. Install dependencies** — this installs the exact package versions recorded by the project:
 
 ```bash
-npm install
+npm ci
 ```
 
 **3. Optimise images** — the optimised image variants are not stored in the repo, so you need to generate them locally before running the site:
@@ -101,6 +101,33 @@ Then open the URL it gives you (usually `http://localhost:5173`) in your browser
 
 ---
 
+## 🧭 How the project fits together
+
+The site is a Vue 3 single-page application built with Vite. Vue starts in `src/main.js`, which mounts `src/App.vue`. The app keeps its intentionally small custom router and translation system rather than introducing larger framework plugins.
+
+- `src/routes/` contains the page components and the bilingual public route table.
+- `src/components/` contains reusable UI building blocks; layout primitives live in `src/components/layout/`.
+- `src/layout/` contains the site-wide navigation and footer.
+- `src/lib/` contains routing, translations, image-path helpers, and the shared YAML loader.
+- `src/lib/locales/{est,en}/` contains escaped JSON translation data for each language.
+- `public/_data/` contains editable YAML for members, mentors, workshops, projects, partners, and pricing.
+- `public/assets/` contains source assets; generated image variants remain ignored.
+- `.storybook/` and `src/stories/` provide isolated Vue component previews.
+
+Page components use Vue's `<script setup>` syntax and Composition API primitives such as `ref` and `computed`. Use `usePageText("PageName")` for page translations, `loadYaml(path, fallback)` for YAML-backed content, and the exported `navigate()` helper for programmatic internal navigation.
+
+Useful commands:
+
+```bash
+npm run dev             # start the local site
+npm run build           # create a production build
+npm run storybook       # preview components in Storybook
+npm run build-storybook # verify the static Storybook build
+npm run optimise        # regenerate local image variants
+```
+
+---
+
 ## 🖼️ Adding images
 
 Place your original image files (PNG, JPG, etc.) into the appropriate `public/assets/{category}/original/` folder, then run:
@@ -119,4 +146,4 @@ The script will generate optimised WebP and JPG variants automatically. **Do not
 
 Nothing to do here — GitHub automatically builds and deploys the site whenever something is pushed to the `v2` branch. The optimised images are generated as part of the build, so you don't need to worry about that either.
 
-It usually takes **2–5 minutes**. You can watch it happen in the [Actions tab](https://github.com/Lapikud/lapikud.github.io/actions).
\ No newline at end of file
+It usually takes **2–5 minutes**. You can watch it happen in the [Actions tab](https://github.com/Lapikud/lapikud.github.io/actions).
diff --git a/src/components/README.md b/src/components/README.md
index b5b8338..8dbdca1 100644
--- a/src/components/README.md
+++ b/src/components/README.md
@@ -1,26 +1,26 @@
-# SVG previews
+# Component previews
 
-use `npm run storybook` which opens a browser window with all the SVG variations. You can also edit the SVG properties in storybook controls.
+Run `npm run storybook` to open the Vue component previews, including every SVG variation. Storybook controls can change the SVG props interactively.
 
 # Components
 
-under components are building blocks that are not layout related.
+Components in this directory are reusable Vue building blocks that are not layout-specific. They use `<script setup>`, Vue props, and the default slot for child content.
 
 ## details
 
 - Button: a simple button component with some styling.
 - Dropdown: a dropdown component that can be used to show/hide content.
 - Slideshow: a simple slideshow component that can be used to show multiple images in a slideshow format. Includes options to enable/disable autoplay and to set the autoplay interval.
-- Svg: a component that renders different SVG icons based on the `type` prop. See the VARIANTS constant in `Svg.svelte` or storybook for the available types.
+- Svg: a component that renders different SVG icons based on the `type` prop. See the `VARIANTS` constant in `Svg.vue` or Storybook for the available types.
 - Image (Use for larger images): a component that renders an image with some styling. It accepts a lot of props. Main ones are `src` (the main image source that is used if anything else fails or not provided), `alt` (the alt text for the image), `srcSet` (a string of comma-separated image sources for different screen sizes, jpg or png files), `webpSrc` (the webp image source as a webp file), `webpSrcSet` (a string of comma-separated webp image sources for different screen sizes). We use 2 webp images: 400 and 800 width, and one jpg image 800 width as default src for fallback.
 
 # Layout components
 
-under components/layout are components that are used to structure the page, such as Container, Stack, Center, etc.
+Components under `components/layout` structure page content. Prefer these shared primitives over duplicating container, spacing, or grid rules in a route.
 
 - Container: a simple container component that centers its content and adds some padding.
 - Stack: a component that stacks its children vertically or horizontally.
 - Center: a component that centers its content both horizontally and vertically.
 - Section: a component that is used to create sections on the page.
 - Card: a component that adds some padding, a border, and a shadow to its content, used to create cards on the page.
-- Grid: a component that creates a CSS grid layout for its children, with customizable columns and gap. It is dynamic and changes automatically with page size, best practice is to set `columns` for desktop and `mobileColumns` for mobile views to control the behavior if needed.
\ No newline at end of file
+- Grid: a component that creates a CSS grid layout for its children, with customizable columns and gap. It is dynamic and changes automatically with page size, best practice is to set `columns` for desktop and `mobileColumns` for mobile views to control the behavior if needed.