alex/qrdamage
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update spec

Browse Source
This commit is contained in:
Alexander Wainwright
2025-12-17 13:39:02 +10:00
parent 84fb0a2d41
commit c0ff659973
1 changed files with 45 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

87
specs/geminini.md
View File

@@ -1,66 +1,69 @@
Here is the refined specification for **Version 0.1.0**. This document is ready to be handed to a developer.
### Specification v0.1.0: Static Client-Side QR Code Generator
### Specification v0.2.0: Multi-Format Static QR Generator
**1. Project Overview**
Build a lightweight, single-page web utility that generates QR codes for URLs entirely within the user's browser. The priority for this version is speed, simplicity, and establishing a robust "no-backend" architecture.
Build a fast, offline-capable single-page application that generates QR codes for various data types (URL, WiFi, Email). The application must feature a responsive split-pane layout and polished, non-jarring visual updates.
**2. Technical Constraints**
* **Architecture:** Static HTML/CSS/JS. No server-side rendering.
* **Backend:** Strictly None. The page must function 100% offline once the initial assets are loaded.
* **Dependencies:** Use a single, lightweight, open-source JavaScript library for QR generation (e.g., `qrcode.js` or `qrcode-svg`). No other external dependencies (no jQuery, no Lodash, etc.).
* **Frameworks:** Forbidden. Use Semantic HTML5, CSS3, and Vanilla ES6+ JavaScript.
* **Performance:**
* Target Google Lighthouse Performance score of 95-100.
* No blocking scripts in the `<head>`.
* Total page weight (gzipped) target: < 50KB.
* **Architecture:** Static HTML/CSS/JS (Vanilla). No frameworks.
* **Backend:** None. Zero network requests after initial load.
* **Performance:** 95+ Lighthouse score.
* **Page Title:** `QR Generator`
**3. Functional Requirements**
* **Input:**
* A single, clearly labeled text input field.
* Placeholder text: "[https://example.com](https://example.com)".
* **Input Modes:**
* The interface must support different input forms based on the selected mode:
1. **URL / Text (Default):** Single Textarea.
2. **WiFi:** Inputs for "SSID" (Network Name), "Password", and "Encryption Type" (WPA/WEP/None). The JS must format this into the standard WiFi string format (e.g., `WIFI:S:MyNetwork;T:WPA;P:mypassword;;`).
3. **Email:** Inputs for "To", "Subject", and "Body".
* **Generation Logic:**
* **Trigger:** The QR code should generate immediately upon a valid entry.
* **Debouncing:** Implement a slight delay (e.g., 300ms) while typing to prevent flashing/performance hits during rapid keystrokes.
* **Correction Level:** Hardcode to 'High' (H) to ensure the code is scan-robust.
* **Output:**
* Render the QR code in the visual center of the page.
* If the input is empty, show a placeholder state or a blank canvas to keep the layout stable.
* **Auto-Update:** The QR code updates automatically as the user types (with debouncing).
* **Error Correction:** High (H).
* **Download:**
* A single button labeled "Download PNG".
* Clicking it downloads the currently generated QR code image.
* Button text: "Download".
* Format: PNG.
**4. UI/UX Design**
**4. UI/UX & Layout Design**
* **Aesthetic:** Minimalist, "Subtle & Elegant."
* **Colors:**
* Background: Off-white / Soft Gray (e.g., `#f4f4f4`).
* Container: White card with subtle shadow.
* QR Code: Standard Black on White.
* **Grid Layout (The "Side-by-Side" Requirement):**
* **Desktop/Tablet:** A two-column layout.
* **Left Pane:** Input controls (Mode selector + Input fields).
* **Right Pane:** The generated QR code + Download button.
* *Vertical alignment:* The QR code should remain sticky or centered vertically as the input form grows.
* **Typography:** System Font Stack (San Francisco, Segoe UI, Roboto) for instant rendering.
* **Layout:**
* Vertical stack: Title -> Input -> QR Display -> Download Button.
* Responsive: The card must fit comfortably on mobile screens without horizontal scrolling.
* **Mobile:** Automatically stack vertically (Inputs on top, QR on bottom) using CSS Media Queries.
* **Visual Stability (The "Anti-Flicker" Requirement):**
* **Fixed Dimensions:** The QR code container must have a reserved, fixed aspect ratio/size to prevent the rest of the page from "jumping" or reflowing when the QR code redraws.
* **Subtle Transition:**
* Use a CSS `transition` on the QR code container (specifically `opacity` or `filter`).
* When the code updates, it should not "flash" white. A standard approach is a very fast (e.g., 200ms) cross-fade or simply keeping the opacity at 1 and letting the canvas repaint instantly.
* *Developer Note:* Avoid destroying and recreating the DOM element if possible; update the canvas context or `src` attribute smoothly.
**5. Deliverables**
* `index.html`
* `style.css`
* `script.js`
* `README.md` (Brief local setup instructions).
**5. Styling Guidelines**
* **Aesthetic:** Clean, professional, minimal.
* **Colors:** Neutral tones. The focus should be on the functionality.
* **Typography:** System fonts.
**6. Deliverables**
* `index.html` (Semantic markup with input forms for all 3 modes).
* `style.css` (Flexbox/Grid for layout + transitions).
* `script.js` (Logic for string formatting WiFi/Email and QR generation).
* `README.md`