From fe6518b26b5c9874b4e4cef98cba1ce6f08c5cc1 Mon Sep 17 00:00:00 2001 From: Malek Wael <166439118+malekwael229@users.noreply.github.com> Date: Wed, 2 Sep 2026 02:33:55 +0300 Subject: [PATCH 1/7] Add FocusTube design brief --- DESIGN.md | 212 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 212 insertions(+) create mode 100644 DESIGN.md diff --git a/DESIGN.md b/DESIGN.md new file mode 100644 index 0000000..4044c51 --- /dev/null +++ b/DESIGN.md @@ -0,0 +1,212 @@ +# Design + +## Source of truth + +**Status:** Active +**Date:** 2026-09-02 +**Product surfaces:** browser-extension popup/options UI, public GitHub Pages landing page, store-facing product presentation. + +Evidence reviewed: + +- Current extension popup structure and existing product styling. +- README product description, supported platforms, privacy model, and project-impact figures. +- Existing GitHub Pages landing-page files under `docs/`. +- GitHub Pages deployment logs showing the repository root is the active publishing source. +- User screenshot of the live site showing the README rendered as the homepage. + +## Brand + +FocusTube should feel calm, focused, technical, and trustworthy. It is a practical productivity tool, not a lifestyle brand or a flashy startup landing page. + +Trust signals: + +- Free and open source. +- No analytics or tracking. +- No account or project-controlled backend. +- Available on Chrome, Firefox, and Edge. +- Real public source, releases, tests, and store listings. + +Avoid: + +- Generic AI-startup aesthetics. +- Decorative gradients, glow effects, excessive shadows, and card grids used only for visual filler. +- Huge marketing copy that pushes the product below the fold. +- Fake browser chrome, fake live counters, or invented usage statistics. +- Repeating the same claim in multiple sections. + +## Product goals + +Goals: + +- Explain the product in one screen: keep useful parts of social sites, remove distracting feeds. +- Make the Chrome install action obvious while keeping Firefox and Edge easy to find. +- Show enough of the extension UI to make the product feel real. +- Establish privacy and open-source trust quickly. +- Work well on desktop and mobile without JavaScript. + +Non-goals: + +- Reproduce every extension setting on the marketing page. +- Turn the landing page into full documentation. +- Add analytics, accounts, tracking, or a backend. +- Add animation or visual effects that do not improve comprehension. + +Success signals: + +- A visitor can identify what FocusTube does within a few seconds. +- Store links are visible without scrolling on common desktop sizes. +- The live root URL serves the product landing page rather than the repository README. + +## Personas and jobs + +Primary personas: + +- Students who need YouTube or social platforms for useful tasks but get pulled into short-form feeds. +- Knowledge workers who want to keep access to specific social-site functions without blocking entire domains. +- Privacy-conscious users who prefer a local, open-source extension. + +Primary jobs: + +- Understand what FocusTube blocks. +- Decide whether it fits the user's browsing habits. +- Install it in the user's browser. +- Verify that it does not track browsing activity. + +## Information architecture + +Public landing page hierarchy: + +1. Header with FocusTube brand, key navigation, GitHub, and install action. +2. Hero with the core promise, browser install links, current project proof, and a product-control preview. +3. Supported-platform strip. +4. Short explanation of how FocusTube removes distracting surfaces while keeping useful pages available. +5. Privacy section. +6. Final install action. +7. Minimal footer with source link. + +The README remains developer/project documentation and must not be used as the public landing-page entry file. + +## Design principles + +1. **Product before prose.** Show what the extension does before explaining every detail. +2. **One primary action.** Chrome is the main install CTA; Firefox and Edge remain visible secondary actions. +3. **Use real product language.** Prefer terms already used by FocusTube and avoid generic productivity slogans. +4. **Trust through restraint.** Privacy and open-source facts should be specific and verifiable, not exaggerated. +5. **No visual filler.** Every panel, border, label, and metric must carry product information. +6. **Preserve brand continuity.** The existing FocusTube blue is intentional product branding, not a default landing-page choice. + +## Visual language + +Color: + +- Base: near-black neutral background. +- Surfaces: restrained dark gray layers. +- Text: high-contrast white with muted gray secondary copy. +- Accent: existing FocusTube blue `#4facfe` with a lighter hover state. +- Success state: muted green only for explicit enabled/status feedback. + +Typography: + +- System-first sans-serif stack using Inter when available. +- Large but controlled hero type; no oversized display text that overwhelms the product preview. +- Body copy at comfortable reading sizes with short line lengths. + +Spacing: + +- Wide desktop breathing room with tighter mobile spacing. +- Prefer separators and whitespace over stacking many boxed cards. + +Shape and elevation: + +- Moderate corner radii on interactive/product-preview surfaces. +- Borders provide separation; avoid gratuitous drop shadows and glow effects. + +Motion: + +- No required motion. Hover transitions should be subtle and functional. + +Imagery and iconography: + +- Use the real FocusTube extension icon. +- Product preview should reflect actual controls and terminology rather than a fake browser window. + +## Components + +Landing-page components: + +- `site-header`: brand, navigation, install shortcut. +- `store-actions`: Chrome primary action plus Firefox and Edge secondary actions. +- `product-shot`: static representation of the extension control surface. +- `supported-strip`: supported-site names. +- `feature-rows`: three concise product behaviors. +- `privacy-section`: direct privacy statement plus specific trust facts. +- `install-section`: final install prompt. +- `site-footer`: brand/source closure. + +Token ownership: + +- Landing-page tokens live in the landing-page stylesheet and must not modify the extension's root `styles.css`. +- Extension UI tokens remain owned by the extension stylesheet. + +## Accessibility + +Target: WCAG 2.2 AA where practical for the static landing page. + +- Semantic `header`, `nav`, `main`, `section`, and `footer` structure. +- Visible keyboard focus on links and controls. +- Decorative icon images use empty alt text; meaningful text remains in the DOM. +- Maintain readable text/background contrast. +- Do not require hover, animation, or color alone to understand content. +- Respect reduced-motion expectations by keeping motion minimal and nonessential. + +## Responsive behavior + +Desktop: + +- Two-column hero with copy and product preview. +- Full navigation visible. +- Privacy content can use two columns. + +Tablet: + +- Hero and privacy sections collapse to one column. +- Product preview moves below the hero copy. + +Mobile: + +- Hide nonessential header links while preserving the install action. +- Stack platform preview items and install controls when needed. +- Keep tap targets comfortably sized. +- Prevent horizontal overflow except the intentionally scrollable supported-platform strip. + +## Interaction states + +The public page is static and has no application loading state. + +- Links: default, hover, and keyboard-focus states. +- Install buttons: clear default and hover/focus states. +- Product preview controls are illustrative, not interactive, and must not imply that settings can be changed on the website. +- If an external store is unavailable, the page itself remains usable and the other store/GitHub links remain available. + +## Content voice + +- Short, direct, and specific. +- Prefer plain language such as "Hide short-form feeds" over marketing jargon. +- Use "FocusTube" consistently. +- Do not claim certification, auditing, or privacy guarantees beyond what the repository supports. +- Do not invent user counts, ratings, time-saved figures, or blocked-count values. + +## Implementation constraints + +- Static HTML and CSS only for the landing page. +- No JavaScript, analytics, tracking pixels, external runtime dependencies, or backend. +- GitHub Pages currently publishes from `main` at the repository root, so the public entry file must be root `index.html` unless Pages settings are deliberately changed later. +- Do not overwrite the extension's root `styles.css`; the landing page uses its own stylesheet. +- Store URLs and GitHub URL must remain the official existing links. +- Required repository CI, CodeQL, and release-verification checks must stay green. +- Public-page changes should be checked at desktop and mobile widths before being considered finished. + +## Open questions + +- [ ] Replace the illustrative extension preview with a polished real product screenshot if a stable screenshot asset is added later. **Owner:** maintainer. **Impact:** medium. +- [ ] Decide later whether project-impact numbers should remain hard-coded on the landing page or be removed to avoid stale public metrics. **Owner:** maintainer. **Impact:** low. From 6b9bb871371b1034f271b3694c50e7f9019a7ff1 Mon Sep 17 00:00:00 2001 From: Malek Wael <166439118+malekwael229@users.noreply.github.com> Date: Wed, 2 Sep 2026 02:34:03 +0300 Subject: [PATCH 2/7] Add Pages entry regression test --- tests/pages-site.test.js | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 tests/pages-site.test.js diff --git a/tests/pages-site.test.js b/tests/pages-site.test.js new file mode 100644 index 0000000..8d9f3df --- /dev/null +++ b/tests/pages-site.test.js @@ -0,0 +1,19 @@ +const assert = require("node:assert/strict"); +const fs = require("node:fs"); +const path = require("node:path"); + +const root = path.resolve(__dirname, ".."); +const read = (file) => fs.readFileSync(path.join(root, file), "utf8"); + +const page = read("index.html"); + +assert.match(page, /FocusTube \| Block Shorts, Reels and distracting feeds<\/title>/); +assert.match(page, /href="docs\/styles\.css"/); +assert.match(page, /href="https:\/\/chromewebstore\.google\.com\/detail\/focustube-distraction-blo\/ppdjgkniggbikifojmkindmbhppmoell"/); +assert.match(page, /href="https:\/\/addons\.mozilla\.org\/addon\/focus-tube\/"/); +assert.match(page, /href="https:\/\/microsoftedge\.microsoft\.com\/addons\/detail\/focustube\/emffahlehkfdlknpmpndaabhigchhoog"/); +assert.match(page, /src="icons\/icon128\.png"/); +assert.doesNotMatch(page, /<script\b/i); +assert.equal(fs.existsSync(path.join(root, "docs", "index.html")), false); + +console.log("Pages entry checks passed."); From 667ba05c119654e91af7a7d764f17434b49ec2ec Mon Sep 17 00:00:00 2001 From: Malek Wael <166439118+malekwael229@users.noreply.github.com> Date: Wed, 2 Sep 2026 02:34:15 +0300 Subject: [PATCH 3/7] Run Pages entry regression test --- scripts/run-test-all.js | 1 + 1 file changed, 1 insertion(+) diff --git a/scripts/run-test-all.js b/scripts/run-test-all.js index 8290149..c6af49a 100644 --- a/scripts/run-test-all.js +++ b/scripts/run-test-all.js @@ -47,6 +47,7 @@ function main() { runSyntaxChecks(); run(process.execPath, [path.join("tests", "package-reproducibility.test.js")]); run(process.execPath, [path.join("tests", "regression.test.js")]); + run(process.execPath, [path.join("tests", "pages-site.test.js")]); run(process.execPath, [path.join("tests", "background-timer.test.js")]); run(process.execPath, [path.join("tests", "playwright-smoke.test.js"), "--build-dir", chromiumBuild], { ...process.env, From 8fb63f1bb282a4b278a057c3e02730aa05a514e6 Mon Sep 17 00:00:00 2001 From: Malek Wael <166439118+malekwael229@users.noreply.github.com> Date: Wed, 2 Sep 2026 02:34:48 +0300 Subject: [PATCH 4/7] Publish landing page from Pages root --- index.html | 152 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 index.html diff --git a/index.html b/index.html new file mode 100644 index 0000000..30c5a4d --- /dev/null +++ b/index.html @@ -0,0 +1,152 @@ +<!doctype html> +<html lang="en"> +<head> + <meta charset="utf-8"> + <meta name="viewport" content="width=device-width, initial-scale=1"> + <meta name="description" content="FocusTube blocks YouTube Shorts, Instagram Reels, TikTok, Facebook Reels and distracting LinkedIn feeds while keeping the useful parts of each site available."> + <meta name="theme-color" content="#0d0f12"> + <title>FocusTube | Block Shorts, Reels and distracting feeds + + + + + + + +
+
+
+
+ Free + Open source + No tracking +
+

Use the site.
Skip the scroll trap.

+

FocusTube removes the parts of social sites that pull you into endless scrolling, without blocking the whole website.

+ +
+
700+users
+
32GitHub stars
+
5.0Chrome rating
+
+
+ +
+ +
+
+ +
+
+ YouTube + Instagram + TikTok + Facebook + LinkedIn +
+
+ +
+
+

Keep what you need. Remove what you don’t.

+

FocusTube targets distracting surfaces instead of taking the lazy approach of blocking entire websites.

+
+ +
+
+ 01 +

Hide short-form feeds

Remove YouTube Shorts, Instagram Reels, Facebook Reels and other high-friction feed surfaces.

+
+
+ 02 +

Keep useful pages available

Search YouTube, open a LinkedIn profile or use the parts of each site you actually came for.

+
+
+ 03 +

Control it per platform

Choose which distractions disappear, then use the built-in focus and break timers when you need more structure.

+
+
+
+ +
+
+

Your browsing data stays yours.

+

FocusTube has no analytics, telemetry, account system or FocusTube-controlled backend. Settings and timer data stay in browser-local storage.

+ Read the privacy notes +
+
+
No analyticsNo usage tracking or analytics SDK.
+
No accountNo sign-up, login or cloud profile.
+
Open sourceInspect the source, tests and releases on GitHub.
+
+
+ +
+
+

Make your browser quieter.

+

Install FocusTube for free. Pick what disappears. Get back to what you opened the site for.

+
+ +
+
+ + + + From 8ab47aa97ef1eb173f8c2fa715129e6a7d48b209 Mon Sep 17 00:00:00 2001 From: Malek Wael <166439118+malekwael229@users.noreply.github.com> Date: Wed, 2 Sep 2026 02:34:55 +0300 Subject: [PATCH 5/7] Remove duplicate Pages entry --- docs/index.html | 150 ------------------------------------------------ 1 file changed, 150 deletions(-) delete mode 100644 docs/index.html diff --git a/docs/index.html b/docs/index.html deleted file mode 100644 index 645bd56..0000000 --- a/docs/index.html +++ /dev/null @@ -1,150 +0,0 @@ - - - - - - - - FocusTube | Block Shorts, Reels and distracting feeds - - - - - -
-
-
-
- Free - Open source - No tracking -
-

Use the site.
Skip the scroll trap.

-

FocusTube removes the parts of social sites that pull you into endless scrolling, without blocking the whole website.

- -
-
700+users
-
32GitHub stars
-
5.0Chrome rating
-
-
- -
- -
-
- -
-
- YouTube - Instagram - TikTok - Facebook - LinkedIn -
-
- -
-
-

Keep what you need. Remove what you don’t.

-

FocusTube targets distracting surfaces instead of taking the lazy approach of blocking entire websites.

-
- -
-
- 01 -

Hide short-form feeds

Remove YouTube Shorts, Instagram Reels, Facebook Reels and other high-friction feed surfaces.

-
-
- 02 -

Keep useful pages available

Search YouTube, open a LinkedIn profile or use the parts of each site you actually came for.

-
-
- 03 -

Control it per platform

Choose which distractions disappear, then use the built-in focus and break timers when you need more structure.

-
-
-
- -
-
-

Your browsing data stays yours.

-

FocusTube has no analytics, telemetry, account system or FocusTube-controlled backend. Settings and timer data stay in browser-local storage.

- Read the privacy notes -
-
-
No analyticsNo usage tracking or analytics SDK.
-
No accountNo sign-up, login or cloud profile.
-
Open sourceInspect the source, tests and releases on GitHub.
-
-
- -
-
-

Make your browser quieter.

-

Install FocusTube for free. Pick what disappears. Get back to what you opened the site for.

-
- -
-
- - - - From 2913112ffd6d470a744ae204d5c7151b4edfa663 Mon Sep 17 00:00:00 2001 From: Malek Wael <166439118+malekwael229@users.noreply.github.com> Date: Wed, 2 Sep 2026 02:35:01 +0300 Subject: [PATCH 6/7] Remove unused docs Pages marker --- docs/.nojekyll | 0 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 docs/.nojekyll diff --git a/docs/.nojekyll b/docs/.nojekyll deleted file mode 100644 index e69de29..0000000 From cd5ecf423d4f1690624be5b7a3884b25240ffc97 Mon Sep 17 00:00:00 2001 From: Malek Wael <166439118+malekwael229@users.noreply.github.com> Date: Wed, 2 Sep 2026 02:35:38 +0300 Subject: [PATCH 7/7] Tighten landing page copy --- index.html | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/index.html b/index.html index 30c5a4d..9d237ca 100644 --- a/index.html +++ b/index.html @@ -93,13 +93,13 @@

Use the site.
Skip the scroll trap.

Keep what you need. Remove what you don’t.

-

FocusTube targets distracting surfaces instead of taking the lazy approach of blocking entire websites.

+

FocusTube targets distracting surfaces instead of blocking entire websites.

01 -

Hide short-form feeds

Remove YouTube Shorts, Instagram Reels, Facebook Reels and other high-friction feed surfaces.

+

Hide short-form feeds

Remove YouTube Shorts, Instagram Reels, Facebook Reels and other distracting feed surfaces.

02 @@ -128,7 +128,7 @@

Your browsing data stays yours.

Make your browser quieter.

-

Install FocusTube for free. Pick what disappears. Get back to what you opened the site for.

+

Install FocusTube for free, choose what disappears, and use the sites for what you opened them for.