Frontend Playground

Purpose

Standard process for adding a new frontend experiment to the playground, and promoting approved prototypes to production SvelteKit apps.

Core Principle: Playground IS Production

SvelteKit .svelte files ARE HTML. A playground prototype is not "inspiration" — it IS the implementation. The promotion path is copy-paste, not rewrite:

1. Copy the <style> block → paste into the .svelte component's scoped <style> (or into app.css for shared styles)
2. Copy the HTML structure → paste into the .svelte template
3. Replace hardcoded text with {data.foo} Svelte bindings
4. Add +page.server.ts to fetch the real data

That's it. No screenshots. No "porting." No interpretation. The prototype IS the code.

Rule

Vanilla HTML, CSS, and JavaScript only. No npm. No SvelteKit. No build step. If it can't be opened directly in a browser, it doesn't belong in the playground.

Playground Structure

Procedure: Create Project Playground Repo

1. Create Forgejo repo — forgejo_admin/[project]-playground
2. Clone locally — git clone ... ~/[project]-playground
3. Add index.html — follow convention-frontend-css (Atkinson Hyperlegible, #fafafa bg, max-width: 48rem, mobile breakpoint 600px). Read pal-e-playground/guide/ first.
4. Add nginx subpath — add a location /[project]/ { alias /srv/[project]-playground/; } block to the playground nginx config + hostPath mount for ~/[project]-playground. This serves the new repo at playground.tail5b443a.ts.net/[project]/.
5. Update hub landing page — add a link to the new subpath in pal-e-playground/index.html. Push to the hub repo.
6. Verify on phone — open playground.tail5b443a.ts.net/[project]/ and confirm it renders.
7. Register — add repo to project-frontend-playground Repos table under Project Playground Repos.
8. Push to Forgejo

   cd ~/[project]-playground
   git add .
   git commit -m "initial prototype"
   git push
   

Procedure: Hub Repo Maintenance

1. The hub repo (pal-e-playground) contains only: guide/index.html (CSS philosophy reference) and index.html (landing page linking to all project subpaths).
2. Landing page is the live directory — it links to every project playground via subpath (e.g. /westside/, /mcd-tracker/). Update it whenever a new project onboards.
3. Guide updates — when CSS conventions change, update convention-frontend-css first, then update the guide to match.
4. No project prototypes in the hub — project prototypes live in their own [project]-playground repos, served as subpaths under the same Tailscale funnel.

Promotion to Production

1. Approve on phone — Lucas verifies the prototype looks right on mobile
2. Create Forgejo issue on target repo (pal-e-app, westside-app, etc.) referencing the prototype path
3. Direct copy-paste — the dev agent's job is mechanical:
   • Copy CSS into scoped <style> or app.css
   • Copy HTML into .svelte template
   • Replace hardcoded hex values with var(--color-*) custom properties
   • Replace hardcoded text/data with {data.foo} Svelte bindings
   • Add +page.server.ts for data fetching
4. QA review — verify zero hardcoded hex, all data bindings correct, mobile responsive
5. Lucas verifies production on phone before merge

Why This Works

SvelteKit components are HTML with superpowers. A .svelte file has three sections: <script>, HTML template, and <style>. The HTML template IS HTML. The <style> IS CSS. The only translation from playground to production is adding the <script> for data binding and replacing static content with template expressions.

Proven by: F11c home page (PR #37). Prototype at html-playground/6-pal-e-home/ → direct port to +page.svelte in one dev agent dispatch.

What NOT to Do

• Don't add package.json to a playground experiment
• Don't try to connect to live APIs from the playground — use hardcoded/fake data
• Don't skip the phone check — if it's not mobile-friendly, it's not ready
• Don't let agents design the look — agents port proven CSS, they don't create it
• Don't use screenshots as an intermediary — the HTML/CSS IS the spec
• Don't "reinterpret" the prototype — copy it literally, then swap data bindings

Related

• project-frontend-playground — parent project
• doc-html-playground — philosophy + infra reference
• convention-frontend-css — CSS custom property rules
• feedback_playground_first — the original feedback that established this convention
• feedback_frontend_iteration — frontend must iterate with Lucas in the loop

Vision

The frontend development practice. Prove visual design with vanilla HTML, CSS, and JavaScript before committing to production repos. Zero framework overhead. Immediate feedback on any device. Lucas iterates here personally — agents don't ship frontend without visual approval.

Rule: vanilla HTML, CSS, and JavaScript only. No npm, no SvelteKit, no build step. If it can't be opened directly in a browser, it doesn't belong in a playground. SvelteKit and framework concerns live in production repos (pal-e-app, westside-app).

User Stories

• As Lucas, I want to prototype a page layout on my phone in minutes, so that I can lock the visual design before any agent writes framework code.
• As Lucas, I want to save an HTML file and immediately see it on my phone via the Tailscale funnel, so that iteration is instant with zero build steps.
• As a new project, I want a clear SOP for creating my own playground repo that follows the established CSS philosophy.
• As a dev agent, I want a proven HTML/CSS prototype to copy-paste into a SvelteKit production app, so that I know exactly what CSS to port.

Architecture

Linked-Repo Model

Each product project owns its own -playground repo. The pal-e-playground repo is the hub — it contains the CSS philosophy guide and landing page, not project prototypes. Project playground repos are listed under both their own project AND under this project as references.

pal-e-playground/              ← hub repo (CSS guide + landing page only)
  index.html                   ← landing page with guide link
  guide/                       ← canonical CSS philosophy reference
    index.html

westside-playground/           ← separate repo, Westside prototypes
mcd-tracker-playground/        ← separate repo, mcd-tracker prototypes (future)

How It Works

Each playground repo is served via nginx hostPath + Tailscale funnel. Save a file locally, refresh the browser on any device — instant. No build, no deploy, no CI.

Frontend Development Workflow

Promotion Path

1. Playground — iterate on HTML+CSS in the project's own playground repo until it looks right on phone
2. The HTML/CSS IS the spec — no screenshots as intermediary
3. Agent ports to production — dev agent copy-pastes the proven CSS into the SvelteKit repo
4. Lucas verifies on device — production result checked on phone before merge

Project Onboarding

When a new project needs a frontend, follow sop-frontend-experiment:

1. Create a [project]-playground Forgejo repo
2. Read convention-frontend-css and the pal-e-playground/guide/ before writing any CSS
3. Prototype with hardcoded/fake data — prove the look, not the data
4. Set up nginx hostPath + Tailscale funnel for phone verification
5. When approved, create Forgejo issue on the production repo referencing the prototype

Status

• pal-e-playground repo: LIVE. Hub + CSS guide. PR #2 merged (2026-03-16).
• westside-playground: Existing, stays as its own repo.
• html-playground: ARCHIVED. Guide content recreated in pal-e-playground.
• Convention + SOP: Updated with linked-repo model, debugging playbook, 3 layout systems, 5 core properties.

Milestones

• 2026-03 (original) — html-playground created. 5 SvelteKit experiments. Experiment #3 promoted to westside-app.
• 2026-03-15 — Philosophy reset: vanilla HTML/CSS/JS only.
• 2026-03-15 — Linked-repo model established. pal-e-playground = hub + CSS guide. Each project owns its own -playground repo. Convention and SOP updated with debugging playbook, 3 layout systems, 5 core properties.

Repos

Hub Repo

Project Playground Repos

Archived

Key Conventions

• convention-frontend-css — the CSS rules, layout systems, debugging playbook
• sop-frontend-experiment — how to create playground repos and onboard projects

Board

No board yet. Work tracked via plan-pal-e-agency Phase 14. Board created when sustained execution begins.