From 0f37e76e9d43de7bdc76740af85c013dd7152e5c Mon Sep 17 00:00:00 2001
From: Maksym Bilan <maximb.mail@gmail.com>
Date: Sun, 3 May 2026 15:41:45 +0200
Subject: [PATCH] Polish public repository presentation

---
 README.md                            | 38 ++++++++++++++---
 docs/screenshots/coin-practice.svg   | 51 +++++++++++++++++++++++
 docs/screenshots/column-practice.svg | 53 ++++++++++++++++++++++++
 docs/screenshots/home.svg            | 62 ++++++++++++++++++++++++++++
 4 files changed, 199 insertions(+), 5 deletions(-)
 create mode 100644 docs/screenshots/coin-practice.svg
 create mode 100644 docs/screenshots/column-practice.svg
 create mode 100644 docs/screenshots/home.svg

diff --git a/README.md b/README.md
index 2c8c5a4..7f81e47 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,35 @@
-# Математика / Matemáticas
+# Plusik Math Trainer
 
-A static bilingual math trainer for a Ukrainian-speaking 6-year-old learning Spanish first-grade math vocabulary. The app is built with Vite, React 18, TypeScript, Tailwind CSS, and localStorage only.
+![CI](https://github.com/maximbilan/Plusik/actions/workflows/ci.yml/badge.svg)
+
+A static bilingual math trainer for Ukrainian-speaking children joining Spanish first grade.
+
+Plusik helps a child practice the exact worksheet-style math skills used in class while seeing Ukrainian and Spanish labels side by side. It is built as a touch-first static app: no backend, no accounts, no analytics, and no AI calls.
+
+## Screenshots
+
+<p>
+  <img src="docs/screenshots/home.svg" alt="Home screen with bilingual module tiles" width="32%" />
+  <img src="docs/screenshots/column-practice.svg" alt="Column addition practice with number pad" width="32%" />
+  <img src="docs/screenshots/coin-practice.svg" alt="Exact coin payment practice" width="32%" />
+</p>
+
+## Highlights
+
+- Ukrainian-first and Spanish-underneath UI, with UK-only and ES-only modes.
+- 13 practice areas: 12 worksheet skill modules plus bilingual word problems.
+- iPad and iPhone friendly: large tap targets, on-screen number pad, no keyboard required.
+- Local-only persistence with `localStorage`.
+- Static Vite SPA deployable to AWS Amplify Hosting.
+- PR CI on Linux with production build and smoke test.
+
+## Tech Stack
+
+- Vite + React 18 + TypeScript
+- Tailwind CSS
+- lucide-react
+- Web Audio API for tiny generated feedback sounds
+- localStorage for progress
 
 ## Develop
 
@@ -44,9 +73,8 @@ Pull requests to `main` run GitHub Actions on Linux (`ubuntu-latest`):
 
 ## What Is Included
 
-- Ukrainian, Ukrainian+Spanish, and Spanish-only language modes.
-- iPad-first touch UI with on-screen number pads and large tap targets.
-- 13 practice areas: the 12 worksheet skill modules plus bilingual word problems.
+- Number recognition, hundred chart, place value, addition/subtraction with and without carrying/borrowing.
+- Decomposition, euro coin counting, exact payment by tapping coins, balance comparisons, fruit equations, and word problems.
 - Local-only persistence under the `math-trainer/v1` localStorage key.
 - No backend, accounts, analytics, database, Firebase, or Amplify backend resources.
 
diff --git a/docs/screenshots/coin-practice.svg b/docs/screenshots/coin-practice.svg
new file mode 100644
index 0000000..6a7ec93
--- /dev/null
+++ b/docs/screenshots/coin-practice.svg
@@ -0,0 +1,51 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1280 720" role="img" aria-label="Coin practice preview">
+  <defs>
+    <linearGradient id="bg" x1="0" x2="1" y1="0" y2="1">
+      <stop offset="0" stop-color="#fff7df"/>
+      <stop offset="1" stop-color="#d7e3fc"/>
+    </linearGradient>
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="150%">
+      <feDropShadow dx="0" dy="18" stdDeviation="18" flood-color="#25324a" flood-opacity="0.14"/>
+    </filter>
+  </defs>
+  <rect width="1280" height="720" fill="url(#bg)"/>
+  <rect x="54" y="50" width="1172" height="112" rx="42" fill="#ffffff" opacity="0.82" stroke="#ffffff" stroke-width="8" filter="url(#shadow)"/>
+  <text x="640" y="96" text-anchor="middle" font-size="36" font-weight="900" fill="#25324a">Заплати рівно</text>
+  <text x="640" y="130" text-anchor="middle" font-size="22" font-weight="900" fill="#7b8496">Paga la cantidad justa</text>
+
+  <rect x="54" y="198" width="1172" height="470" rx="44" fill="#ffffff" opacity="0.82" stroke="#ffffff" stroke-width="8" filter="url(#shadow)"/>
+  <text x="370" y="270" text-anchor="middle" font-size="34" font-weight="900" fill="#25324a">Торкнись монет, які потрібні</text>
+  <text x="370" y="304" text-anchor="middle" font-size="20" font-weight="800" fill="#7b8496">Toca las monedas que necesitas</text>
+
+  <rect x="240" y="344" width="260" height="128" rx="34" fill="#ffcf5a" filter="url(#shadow)"/>
+  <text x="370" y="384" text-anchor="middle" font-size="22" font-weight="900" fill="#25324a">Ціна / Precio</text>
+  <text x="370" y="440" text-anchor="middle" font-size="62" font-weight="900" fill="#25324a" font-family="Menlo, monospace">52</text>
+
+  <rect x="118" y="512" width="520" height="108" rx="34" fill="#fff7df"/>
+  <g transform="translate(154 535)">
+    <circle cx="38" cy="38" r="34" fill="#d9a463" stroke="#25324a" stroke-width="5"/>
+    <text x="38" y="47" text-anchor="middle" font-size="22" font-weight="900" fill="#25324a">50c</text>
+    <g stroke="#d84a48" stroke-width="8" stroke-linecap="round"><line x1="12" y1="12" x2="64" y2="64"/><line x1="64" y1="12" x2="12" y2="64"/></g>
+  </g>
+  <g transform="translate(254 535)">
+    <circle cx="38" cy="38" r="34" fill="#d9a463" stroke="#25324a" stroke-width="5"/>
+    <text x="38" y="47" text-anchor="middle" font-size="22" font-weight="900" fill="#25324a">2c</text>
+    <g stroke="#d84a48" stroke-width="8" stroke-linecap="round"><line x1="12" y1="12" x2="64" y2="64"/><line x1="64" y1="12" x2="12" y2="64"/></g>
+  </g>
+  <g transform="translate(354 535)">
+    <circle cx="38" cy="38" r="34" fill="#d9a463" stroke="#25324a" stroke-width="5"/>
+    <text x="38" y="47" text-anchor="middle" font-size="22" font-weight="900" fill="#25324a">20c</text>
+  </g>
+  <g transform="translate(454 535)">
+    <circle cx="38" cy="38" r="34" fill="#d9a463" stroke="#25324a" stroke-width="5"/>
+    <text x="38" y="47" text-anchor="middle" font-size="22" font-weight="900" fill="#25324a">10c</text>
+  </g>
+
+  <rect x="790" y="276" width="260" height="142" rx="34" fill="#ffffff" opacity="0.85" filter="url(#shadow)"/>
+  <text x="920" y="318" text-anchor="middle" font-size="24" font-weight="900" fill="#25324a">Обрано</text>
+  <text x="920" y="348" text-anchor="middle" font-size="17" font-weight="800" fill="#7b8496">Seleccionado</text>
+  <text x="920" y="392" text-anchor="middle" font-size="56" font-weight="900" fill="#25324a" font-family="Menlo, monospace">52</text>
+  <rect x="790" y="462" width="260" height="86" rx="30" fill="#b8e6c9" filter="url(#shadow)"/>
+  <text x="920" y="500" text-anchor="middle" font-size="24" font-weight="900" fill="#25324a">Перевірити</text>
+  <text x="920" y="528" text-anchor="middle" font-size="17" font-weight="800" fill="#7b8496">Comprobar</text>
+</svg>
diff --git a/docs/screenshots/column-practice.svg b/docs/screenshots/column-practice.svg
new file mode 100644
index 0000000..6101345
--- /dev/null
+++ b/docs/screenshots/column-practice.svg
@@ -0,0 +1,53 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1280 720" role="img" aria-label="Column math practice preview">
+  <defs>
+    <linearGradient id="bg" x1="0" x2="1" y1="0" y2="1">
+      <stop offset="0" stop-color="#fff7df"/>
+      <stop offset="1" stop-color="#d7e3fc"/>
+    </linearGradient>
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="150%">
+      <feDropShadow dx="0" dy="18" stdDeviation="18" flood-color="#25324a" flood-opacity="0.14"/>
+    </filter>
+  </defs>
+  <rect width="1280" height="720" fill="url(#bg)"/>
+  <rect x="46" y="36" width="1188" height="128" rx="44" fill="#ffffff" opacity="0.82" stroke="#ffffff" stroke-width="8" filter="url(#shadow)"/>
+  <rect x="86" y="70" width="94" height="64" rx="24" fill="#25324a"/>
+  <text x="133" y="101" text-anchor="middle" font-size="20" font-weight="900" fill="#ffffff">Назад</text>
+  <text x="133" y="126" text-anchor="middle" font-size="16" font-weight="800" fill="#ffffff" opacity="0.68">Atrás</text>
+  <text x="640" y="91" text-anchor="middle" font-size="36" font-weight="900" fill="#25324a">Додавання з переходом</text>
+  <text x="640" y="128" text-anchor="middle" font-size="22" font-weight="900" fill="#7b8496">Suma llevando</text>
+  <text x="1090" y="103" font-size="22" font-weight="900" fill="#25324a">Зірочки</text>
+  <text x="1090" y="132" font-size="16" font-weight="800" fill="#7b8496">Estrellas</text>
+
+  <rect x="54" y="198" width="1172" height="470" rx="44" fill="#ffffff" opacity="0.82" stroke="#ffffff" stroke-width="8" filter="url(#shadow)"/>
+  <text x="335" y="270" text-anchor="middle" font-size="36" font-weight="900" fill="#25324a">Порахуй у стовпчик</text>
+  <text x="335" y="304" text-anchor="middle" font-size="22" font-weight="800" fill="#7b8496">Calcula en columna</text>
+
+  <rect x="180" y="330" width="320" height="250" rx="34" fill="#fff7df"/>
+  <text x="310" y="378" font-size="22" font-weight="900" fill="#7b8496">Десятки</text>
+  <text x="397" y="378" font-size="22" font-weight="900" fill="#7b8496">Одиниці</text>
+  <text x="305" y="458" text-anchor="middle" font-size="78" font-weight="900" fill="#25324a" font-family="Menlo, monospace">4</text>
+  <text x="405" y="458" text-anchor="middle" font-size="78" font-weight="900" fill="#25324a" font-family="Menlo, monospace">8</text>
+  <text x="226" y="538" text-anchor="middle" font-size="78" font-weight="900" fill="#25324a" font-family="Menlo, monospace">+</text>
+  <text x="305" y="538" text-anchor="middle" font-size="78" font-weight="900" fill="#25324a" font-family="Menlo, monospace">3</text>
+  <text x="405" y="538" text-anchor="middle" font-size="78" font-weight="900" fill="#25324a" font-family="Menlo, monospace">5</text>
+  <line x1="205" y1="558" x2="470" y2="558" stroke="#25324a" stroke-width="8" stroke-linecap="round"/>
+  <rect x="258" y="585" width="88" height="72" rx="18" fill="#ffffff" stroke="#b8bdc8" stroke-width="5" stroke-dasharray="14 12"/>
+  <rect x="362" y="585" width="88" height="72" rx="18" fill="#ffffff" stroke="#b8bdc8" stroke-width="5" stroke-dasharray="14 12"/>
+
+  <g filter="url(#shadow)">
+    <rect x="720" y="250" width="128" height="88" rx="26" fill="#ffffff"/>
+    <rect x="880" y="250" width="128" height="88" rx="26" fill="#ffffff"/>
+    <rect x="1040" y="250" width="128" height="88" rx="26" fill="#ffffff"/>
+    <rect x="720" y="362" width="128" height="88" rx="26" fill="#ffffff"/>
+    <rect x="880" y="362" width="128" height="88" rx="26" fill="#ffffff"/>
+    <rect x="1040" y="362" width="128" height="88" rx="26" fill="#ffffff"/>
+    <rect x="720" y="474" width="128" height="88" rx="26" fill="#ffffff"/>
+    <rect x="880" y="474" width="128" height="88" rx="26" fill="#ffffff"/>
+    <rect x="1040" y="474" width="128" height="88" rx="26" fill="#ffffff"/>
+  </g>
+  <g font-size="48" font-weight="900" fill="#25324a" font-family="Menlo, monospace" text-anchor="middle">
+    <text x="784" y="309">1</text><text x="944" y="309">2</text><text x="1104" y="309">3</text>
+    <text x="784" y="421">4</text><text x="944" y="421">5</text><text x="1104" y="421">6</text>
+    <text x="784" y="533">7</text><text x="944" y="533">8</text><text x="1104" y="533">9</text>
+  </g>
+</svg>
diff --git a/docs/screenshots/home.svg b/docs/screenshots/home.svg
new file mode 100644
index 0000000..e699d16
--- /dev/null
+++ b/docs/screenshots/home.svg
@@ -0,0 +1,62 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1280 720" role="img" aria-label="Plusik home screen preview">
+  <defs>
+    <linearGradient id="bg" x1="0" x2="1" y1="0" y2="1">
+      <stop offset="0" stop-color="#fff7df"/>
+      <stop offset="1" stop-color="#d7e3fc"/>
+    </linearGradient>
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="150%">
+      <feDropShadow dx="0" dy="18" stdDeviation="18" flood-color="#25324a" flood-opacity="0.14"/>
+    </filter>
+  </defs>
+  <rect width="1280" height="720" fill="url(#bg)"/>
+  <circle cx="130" cy="70" r="180" fill="#ffcf5a" opacity="0.35"/>
+  <circle cx="1110" cy="110" r="190" fill="#8ecae6" opacity="0.32"/>
+  <circle cx="780" cy="680" r="210" fill="#b8e6c9" opacity="0.4"/>
+
+  <rect x="54" y="44" width="1172" height="142" rx="46" fill="#ffffff" opacity="0.82" stroke="#ffffff" stroke-width="8" filter="url(#shadow)"/>
+  <rect x="92" y="78" width="78" height="78" rx="28" fill="#ffcf5a"/>
+  <text x="131" y="130" text-anchor="middle" font-size="38" font-weight="900" fill="#25324a">12</text>
+  <text x="200" y="111" font-size="42" font-weight="900" fill="#25324a">Математика</text>
+  <text x="202" y="148" font-size="24" font-weight="800" fill="#7b8496">Matemáticas</text>
+  <rect x="905" y="74" width="270" height="84" rx="30" fill="#ffffff" opacity="0.75"/>
+  <text x="932" y="104" font-size="18" font-weight="900" fill="#25324a">Мова</text>
+  <text x="932" y="130" font-size="15" font-weight="700" fill="#7b8496">Idioma</text>
+  <rect x="1010" y="92" width="72" height="46" rx="18" fill="#25324a"/>
+  <text x="1046" y="122" text-anchor="middle" font-size="16" font-weight="900" fill="#ffffff">UK+ES</text>
+  <rect x="1090" y="92" width="54" height="46" rx="18" fill="#ffffff"/>
+  <text x="1117" y="122" text-anchor="middle" font-size="16" font-weight="900" fill="#25324a">ES</text>
+
+  <g filter="url(#shadow)">
+    <rect x="70" y="228" width="260" height="170" rx="36" fill="#8ecae6" opacity="0.46" stroke="#ffffff" stroke-width="7"/>
+    <rect x="102" y="260" width="58" height="58" rx="22" fill="#ffffff" opacity="0.85"/>
+    <text x="131" y="298" text-anchor="middle" font-size="30" font-weight="900" fill="#25324a">#1</text>
+    <text x="102" y="350" font-size="27" font-weight="900" fill="#25324a">Впізнай число</text>
+    <text x="102" y="380" font-size="18" font-weight="800" fill="#7b8496">Reconoce el número</text>
+
+    <rect x="370" y="228" width="260" height="170" rx="36" fill="#b8e6c9" opacity="0.58" stroke="#ffffff" stroke-width="7"/>
+    <rect x="402" y="260" width="58" height="58" rx="22" fill="#ffffff" opacity="0.85"/>
+    <text x="431" y="298" text-anchor="middle" font-size="30" font-weight="900" fill="#25324a">#2</text>
+    <text x="402" y="350" font-size="27" font-weight="900" fill="#25324a">Сотенна таблиця</text>
+    <text x="402" y="380" font-size="18" font-weight="800" fill="#7b8496">Tabla del 100</text>
+
+    <rect x="670" y="228" width="260" height="170" rx="36" fill="#ffcf5a" opacity="0.52" stroke="#ffffff" stroke-width="7"/>
+    <rect x="702" y="260" width="58" height="58" rx="22" fill="#ffffff" opacity="0.85"/>
+    <text x="731" y="298" text-anchor="middle" font-size="30" font-weight="900" fill="#25324a">#3</text>
+    <text x="702" y="350" font-size="25" font-weight="900" fill="#25324a">Десятки й одиниці</text>
+    <text x="702" y="380" font-size="18" font-weight="800" fill="#7b8496">Decenas y unidades</text>
+
+    <rect x="970" y="228" width="260" height="170" rx="36" fill="#8ecae6" opacity="0.46" stroke="#ffffff" stroke-width="7"/>
+    <rect x="1002" y="260" width="58" height="58" rx="22" fill="#ffffff" opacity="0.85"/>
+    <text x="1031" y="298" text-anchor="middle" font-size="30" font-weight="900" fill="#25324a">#4</text>
+    <text x="1002" y="350" font-size="27" font-weight="900" fill="#25324a">Додавання</text>
+    <text x="1002" y="380" font-size="18" font-weight="800" fill="#7b8496">Suma sin llevar</text>
+
+    <rect x="70" y="438" width="260" height="170" rx="36" fill="#b8e6c9" opacity="0.58" stroke="#ffffff" stroke-width="7"/>
+    <text x="102" y="530" font-size="27" font-weight="900" fill="#25324a">Заплати рівно</text>
+    <text x="102" y="560" font-size="18" font-weight="800" fill="#7b8496">Paga la cantidad justa</text>
+
+    <rect x="370" y="438" width="260" height="170" rx="36" fill="#ffcf5a" opacity="0.52" stroke="#ffffff" stroke-width="7"/>
+    <text x="402" y="530" font-size="27" font-weight="900" fill="#25324a">Що важче?</text>
+    <text x="402" y="560" font-size="18" font-weight="800" fill="#7b8496">¿Qué pesa más?</text>
+  </g>
+</svg>