Developer Guidelines

Platform Rules Brand & Logo Colors Typography Layout & Components Tech Stack Publishing Process Launch Checklist

Platform Rules

These are non-negotiable. Every app on FreeAppStore must follow these principles:

One app per category

There will never be two chess apps, two audiobook readers, or two calendars. One in Free, one in Pro. That's it. No fragmentation.

Free means free

No freemium, no ads, no plans, no paywalls, no "upgrade to unlock." If it's on FreeAppStore, it stays free forever.

Real apps, not websites

Every app must work as a PWA. Save to home screen, use offline, feel native. If it only works in a browser tab, it's not ready.

Private by default

Zero tracking, zero analytics, zero cookies, zero data collection. All user data stays on-device in localStorage.

Open source

MIT license. Public repo on the freeappstore-online GitHub org. Anyone can read the code, verify privacy claims, and contribute.

Brand & Logo

Wordmark

The logo is a wordmark, not an icon. Written as one word with "App" highlighted in the platform accent color:

FreeAppStore — blue accent (#2563eb)
ProAppStore — purple accent (#7c3aed)

Naming rules

Always one word, PascalCase: FreeAppStore
Never three words: ~~Free App Store~~
Never all-caps: ~~FREEAPPSTORE~~

App naming

Context	Format	Example
GitHub repo	lowercase, no prefix	`freebooks`
Package name	lowercase + "app"	`freebooksapp`
Display name	Single word, capitalized	Books
Subdomain	lowercase.freeappstore.online	`books.freeappstore.online`

Colors

Shared neutral palette (all apps)

Every app uses the same neutral palette for UI chrome. Only the accent color differs per app.

Token	Light	Dark	Usage
`--paper`	#fefdfb	#141413	Page background
`--ink`	#1a1917	#f2f0ed	Primary text
`--muted`	#8a8780	#7a7770	Secondary text
`--line`	#e8e5e0	#2a2825	Borders
`--panel`	#f5f3f0	#1e1d1b	Panel background
`--glass`	rgba with 0.7 opacity		Frosted glass overlays
`--success`	#22c55e	#4ade80	Correct / positive
`--warning`	#f59e0b	#fbbf24	Caution
`--error`	#ef4444	#f87171	Wrong / destructive

App accent colors

Each app gets ONE accent color. Used for active states, primary buttons, and highlights.

App	Accent	Rationale
Chess	`#5b7db1`	Calm blue — strategic
Language	`#da5b37`	Warm terracotta — cultural
Math	`#4d70dc`	Confident blue — precise
Music	`#6ECE9E`	Teal green — creative
Puzzle	`#ff8a54`	Energetic orange — playful
Quiz	`#d86f4d`	Warm orange — engaging
Books	`#c08552`	Golden brown — literary

Typography

Font families

Role	Family	Weights	Usage
Body	Manrope	400, 500, 600, 700, 800	All UI text, labels, body
Display	Fraunces	700, 800	Headlines, card titles

Load fonts

<link href="https://fonts.googleapis.com/css2?family=Manrope:wght@400;500;600;700;800&family=Fraunces:opsz,wght@9..144,700;9..144,800&display=swap" rel="stylesheet">

Type scale

Token	Size	Usage
`--text-xs`	0.65rem	Labels, badges, uppercase tags
`--text-sm`	0.85rem	Secondary text, hints
`--text-base`	1rem	Body text
`--text-lg`	1.2rem	Subheadings
`--text-xl`	1.5rem	Section titles
`--text-2xl`	2rem	Page titles

Layout & Components

App shell

All apps use the same responsive shell pattern:

Desktop (≥1024px):
┌──────────────────────────────────────────┐
│  ┌─────────┐  ┌──────────────────────┐   │
│  │ Sidebar │  │     Main Content     │   │
│  │ (17rem) │  │                      │   │
│  │         │  │                      │   │
│  │ - Nav   │  │                      │   │
│  │ - Tools │  │                      │   │
│  └─────────┘  └──────────────────────┘   │
└──────────────────────────────────────────┘

Mobile (<1024px):
┌──────────────────────┐
│      App Header      │
├──────────────────────┤
│                      │
│    Main Content      │
│                      │
├──────────────────────┤
│    Bottom Dock       │
└──────────────────────┘

Key measurements

Element	Value
Sidebar width	`17rem`
Card border radius	`1.25rem`
Button border radius	`0.75rem`
Card padding	`1.5rem`
Grid gap	`1.25rem`
Page margin (mobile)	`1.5rem`
Page margin (desktop)	`2rem`

Component specs

Cards

Background: var(--surface) or var(--panel)
Border: 1px solid var(--line)
Hover: translateY(-2px) + shadow lift
Transition: 200ms ease

Buttons

Primary: accent background, white text
Active state: scale(0.985)
Transition: 160ms ease

Mobile dock

Fixed bottom, full width
Backdrop blur + var(--dock) background
Safe area padding: env(safe-area-inset-bottom)
2-4 tab buttons max

Dark mode

All apps follow the system preference via prefers-color-scheme: dark. No manual toggle. Colors are defined as CSS custom properties with separate light/dark values.

Motion

Fast (buttons): 120ms ease
Base (cards, panels): 200ms ease
Slow (overlays): 300ms ease
Always respect prefers-reduced-motion

App Types

Standalone apps (no backend)

Pure client-side apps with no server. All data lives in localStorage. No account required. Examples: Chess, Quiz, Puzzle, Math, Books.

Frontend only — React + Vite deployed to Cloudflare Pages
Zero backend infrastructure
Works fully offline after first load

Connected apps (shared backend)

Free and Pro versions share the same backend. Same database, same users. The free app provides limited features; the pro app unlocks the full experience.

Both frontends connect to the same Firebase project
User roles (free/pro) determine feature access
Firestore rules enforce access control server-side
Backend code (Functions, rules) lives in the pro repo
Free users can upgrade seamlessly — their data is already there

Examples of connected apps

Bandmates — Free: discover bands, browse profiles. Pro: create bands, messaging, scheduling.
Meetup — Free: browse events, RSVP. Pro: create/host events, groups, analytics.
Language — Free: flashcards, exercises (local). Pro: AI translation, cloud sync.

Tech Stack

Layer	Choice	Version
Language	TypeScript	^5.7
Framework	React	^19.0
Bundler	Vite	^6.0
Styling	Tailwind CSS	^4.1
Hosting (frontend)	Cloudflare Pages	—
Backend (connected)	Firebase	Firestore, Auth, Functions
Package Manager	pnpm	^10.30
Node	—	≥20.19

Project structure

app-name/
├── package.json           (workspace root)
├── pnpm-workspace.yaml    (packages: [web])
├── .gitignore
└── web/
    ├── index.html
    ├── package.json       (@appname/web)
    ├── vite.config.ts
    ├── tsconfig.json
    ├── public/
    │   └── manifest.json  (PWA manifest)
    └── src/
        ├── main.tsx
        ├── index.css       (Tailwind + CSS variables)
        ├── App.tsx
        ├── types.ts
        ├── components/
        ├── hooks/
        └── services/

Publishing Process

How apps get deployed

Push to main — developer pushes code to the GitHub repo
Cloudflare Pages builds — automatic build triggered on push (runs pnpm install && pnpm build)
Deploy to edge — built assets deployed to Cloudflare's global CDN
Live on subdomain — available at appname.freeappstore.online

No CI/CD configuration needed. No tokens to manage. Cloudflare Pages is connected directly to GitHub — push and it deploys.

How a new app gets listed

Propose — Open an issue on GitHub describing the app and its category
Build — Develop the app following these guidelines
Review — The app is reviewed against the launch checklist below
Publish — Repo is added to the org, CF Pages project is created, subdomain is assigned
Listed — App card is added to the FreeAppStore landing page

Infrastructure setup (for maintainers)

# 1. Create GitHub repo
gh repo create freeappstore-online/freeappname --public

# 2. Create Cloudflare Pages project (via API)
#    - Connected to GitHub repo
#    - Build command: pnpm install && pnpm build
#    - Output dir: web/dist
#    - Node version: 22

# 3. Add custom domain
#    appname.freeappstore.online → CF Pages project

# 4. Add app card to freeappstore landing page index.html

Launch Checklist

Every app must pass ALL of these before listing:

Functionality

Core feature works on mobile (320px+)
Core feature works on desktop (1024px+)
Core feature works offline (after first load)
Data persists across sessions (localStorage)
No console errors in production build

Design

Uses Manrope + Fraunces fonts
Uses shared CSS custom properties for neutrals
Has a single app-specific accent color
Follows sidebar (desktop) + dock (mobile) pattern
Supports dark mode via system preference
Respects safe area insets (notched phones)

PWA

Has manifest.json with name, icons, theme color
Includes apple-mobile-web-app-capable meta tag
Registers a service worker
Works when added to home screen

Privacy

Zero network requests for tracking/analytics
No cookies
No external scripts (CDN fonts are OK)
All user data in localStorage only

Performance

First load <2s on 3G
Core JS bundle <100KB gzipped
No layout shift after load

Code

TypeScript with strict mode
No any types
Clean build with zero warnings
MIT license in repo

Ready to build?

Fork an existing app as a starting point, or start fresh. Either way, follow these guidelines and your app will fit right in.

GitHub Organization →

Contents