Initial commit of specs
This commit is contained in:
Alexander Wainwright
164
specs/chatgpt_0.1.0.md
Normal file
164
specs/chatgpt_0.1.0.md
Normal file
@@ -0,0 +1,164 @@
|
||||
## QR Code Generator Website Spec v0.1.0
|
||||
|
||||
### 1) Purpose
|
||||
|
||||
Provide a tiny, static website that generates a QR code for a **URL** entirely on the user’s device.
|
||||
|
||||
### 2) Key constraints
|
||||
|
||||
* **No backend.** After the initial page load, the app performs **no network communication** of any kind.
|
||||
* **Extremely fast to load.** Minimal assets, minimal JS, no frameworks.
|
||||
* **Traditional web.** Plain HTML + CSS + vanilla JS; no dynamic imports, no runtime downloads.
|
||||
* **Pleasant, subtle UI.** Simple, elegant styling using basic CSS and system fonts.
|
||||
|
||||
---
|
||||
|
||||
## 3) Functional requirements
|
||||
|
||||
### 3.1 Inputs
|
||||
|
||||
* A single text input labelled **URL**.
|
||||
* User can paste or type a URL.
|
||||
|
||||
### 3.2 Validation & normalization
|
||||
|
||||
* The app should treat the input as a URL string to encode.
|
||||
* If the user enters a value without a scheme (e.g. `example.com`), normalize by prefixing `https://`.
|
||||
* If the value cannot reasonably be treated as a URL, display a short error message and do not generate a QR code.
|
||||
|
||||
### 3.3 QR generation
|
||||
|
||||
* Generate a QR code from the normalized URL locally in the browser.
|
||||
* Display the QR code preview immediately after valid input is present.
|
||||
* Update the preview as the input changes (debounced to prevent jank while typing).
|
||||
|
||||
### 3.4 Export
|
||||
|
||||
* Provide a single action: **Download PNG**.
|
||||
* The downloaded PNG must match the currently displayed QR code.
|
||||
* Default PNG size: choose one sensible size for v0.1.0 (e.g. 512×512) and keep it fixed for now.
|
||||
|
||||
### 3.5 Reset
|
||||
|
||||
* Provide a **Clear** action that empties the input and removes the QR preview (or replaces it with a placeholder state).
|
||||
|
||||
---
|
||||
|
||||
## 4) UX and UI requirements
|
||||
|
||||
### 4.1 Layout
|
||||
|
||||
Single page, centered column:
|
||||
|
||||
* Title: “QR Code Generator”
|
||||
* URL input
|
||||
* Inline validation/error text (only when needed)
|
||||
* QR preview area (shows placeholder state when empty)
|
||||
* Actions row: Download PNG, Clear
|
||||
|
||||
### 4.2 Styling
|
||||
|
||||
* Use system font stack only.
|
||||
* Subtle borders, light spacing, modest rounding.
|
||||
* No heavy animation; at most a very subtle transition on preview update.
|
||||
* Responsive: usable on mobile and desktop; input and buttons are comfortably tappable.
|
||||
|
||||
### 4.3 Accessibility
|
||||
|
||||
* Label associated with input (`<label for=...>`).
|
||||
* Keyboard navigation works (Tab order sensible).
|
||||
* Visible focus styles.
|
||||
* Error text is readable and associated with the input.
|
||||
|
||||
---
|
||||
|
||||
## 5) Performance requirements
|
||||
|
||||
### 5.1 Load performance
|
||||
|
||||
* Ship as a static site: either a single `index.html` with inline CSS/JS or small separate files (`style.css`, `app.js`).
|
||||
* No external resources (no CDNs, no hosted fonts, no analytics scripts).
|
||||
* Keep total compressed payload small (target: “tiny”; exact budget can be decided later).
|
||||
|
||||
### 5.2 Runtime performance
|
||||
|
||||
* Input-to-preview updates should feel instantaneous for normal URLs.
|
||||
* Use a short debounce (e.g. ~100 ms) on typing updates.
|
||||
|
||||
---
|
||||
|
||||
## 6) Privacy & security requirements
|
||||
|
||||
### 6.1 Offline after load
|
||||
|
||||
* After initial page load, no `fetch`, XHR, beacons, websockets, or external resource loads.
|
||||
* No third-party assets referenced by URL.
|
||||
|
||||
### 6.2 Recommended hardening (static-friendly)
|
||||
|
||||
* Include a Content Security Policy (CSP) that blocks external connections and limits resource sources to self.
|
||||
* Do not persist user input (no localStorage) in v0.1.0.
|
||||
|
||||
---
|
||||
|
||||
## 7) Browser support
|
||||
|
||||
* Must work on current Chrome, Firefox, Safari, and Edge.
|
||||
* If any export feature is unsupported in a given browser, present a clear message (though PNG download should be broadly supported).
|
||||
|
||||
---
|
||||
|
||||
## 8) Technical approach
|
||||
|
||||
### 8.1 Implementation style
|
||||
|
||||
* Vanilla JS and DOM APIs only.
|
||||
* No framework, no build step required (build step optional only if it materially reduces size).
|
||||
|
||||
### 8.2 QR generation dependency
|
||||
|
||||
* Use a small, permissively licensed QR generation library vendored into the repository (bundled or included locally).
|
||||
* The library must not perform network requests.
|
||||
* Keep the dependency footprint minimal.
|
||||
|
||||
### 8.3 Rendering
|
||||
|
||||
* Render QR to a `<canvas>` for preview.
|
||||
* PNG download should be produced from the same canvas.
|
||||
|
||||
---
|
||||
|
||||
## 9) Acceptance criteria (testable)
|
||||
|
||||
* With devtools Network tab open: after initial load, interacting with the page triggers **zero** network requests.
|
||||
* Pasting `https://example.com` produces a scannable QR code.
|
||||
* Entering `example.com` produces a QR code for `https://example.com`.
|
||||
* Entering invalid input shows an error and does not generate a QR code.
|
||||
* “Download PNG” downloads a PNG that scans correctly.
|
||||
* “Clear” resets the UI to the initial state.
|
||||
|
||||
---
|
||||
|
||||
## 10) Deliverables
|
||||
|
||||
* Static site files:
|
||||
|
||||
* `index.html`
|
||||
* (optional) `style.css`, `app.js`
|
||||
* vendored QR library file(s)
|
||||
* README:
|
||||
|
||||
* how to run locally (open file vs local static server)
|
||||
* how to deploy (any static hosting)
|
||||
* privacy statement: “runs entirely in your browser; no network after load”
|
||||
|
||||
---
|
||||
|
||||
## Notes for later versions (explicitly out of scope for v0.1.0)
|
||||
|
||||
* Customisation options (error correction, sizes, colors, margins)
|
||||
* Content types beyond URL
|
||||
* SVG export
|
||||
* PWA/offline installability
|
||||
* Persistence of settings/history
|
||||
* Explicit max data length/QR version targets
|
||||
66
specs/geminini_0.1.0.md
Normal file
66
specs/geminini_0.1.0.md
Normal file
@@ -0,0 +1,66 @@
|
||||
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
|
||||
|
||||
**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.
|
||||
|
||||
**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.
|
||||
|
||||
|
||||
|
||||
**3. Functional Requirements**
|
||||
|
||||
* **Input:**
|
||||
* A single, clearly labeled text input field.
|
||||
* Placeholder text: "[https://example.com](https://example.com)".
|
||||
|
||||
|
||||
* **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.
|
||||
|
||||
|
||||
* **Download:**
|
||||
* A single button labeled "Download PNG".
|
||||
* Clicking it downloads the currently generated QR code image.
|
||||
|
||||
|
||||
|
||||
**4. UI/UX 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.
|
||||
|
||||
|
||||
* **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.
|
||||
|
||||
|
||||
|
||||
**5. Deliverables**
|
||||
|
||||
* `index.html`
|
||||
* `style.css`
|
||||
* `script.js`
|
||||
* `README.md` (Brief local setup instructions).
|
||||
Reference in New Issue
Block a user