Shuuka Platform Documentation

This is the external specification for developers building on Shuuka.

There are two builder tracks:

• Apps — interactive experiences that run inside Shuuka profiles: forms, giveaways, cards, dashboards, and more
• Themes — complete profile presentation layers that control layout, background, fonts, link styling, and app card appearance

The platform handles routing, runtime injection, asset delivery, storage, preview, and data contracts. Builders work from the uploaded bundle contract — no access to Shuuka's internal source tree is needed or granted.

---

Quick Decision

I want to build…	Track
A lead capture form, giveaway, or booking widget	App
An owner analytics dashboard or export tool	App (with admin pages)
A profile card with interactive UI	App
A completely custom profile layout and visual system	Theme
A branded design with specific fonts, backgrounds, and card styles	Theme
Control over how all installed app cards look on a profile	Theme

If you are unsure, start with apps. Themes require building a full layout runtime.

---

Build an App

Apps run inside installed app slots on the profile. They can show content to visitors, collect data, and give the profile owner a custom admin dashboard.

Start here:

1. Platform overview — understand the platform contract
2. App quickstart — build and upload your first app
3. App configuration surfaces — understand settings vs instance settings vs admin pages
4. App lifecycle — understand context injection and SDK initialization
5. App manifest — full manifest.json reference
6. App platform values — all runtime variables, window.__shuukaCtx, and shkApi reference
7. Building forms — complete form-building guide with working examples
8. App admin pages — build custom owner dashboards with working examples

Then, depending on your app:

• App instance settings — per-card sidebar configuration
• App global settings and forms — complete field type reference
• React apps — React-specific patterns and SDK hooks
• App SDK UI helpers — modals, resize, fullsize, bottom sheet
• App data, storage, and access — storage, entries, access codes
• App design and UX — .shk-host-card, .shk-host-btn, dark mode
• Developer mode — test against real data without uploading

---

Build a Theme

Themes take full visual ownership of the profile page. They control everything from the wallpaper to the card container styling.

Start here:

1. Platform overview — understand the platform contract
2. Theme quickstart — minimal working HTML theme with example code
3. Theme manifest — full theme.config.json reference
4. Theme platform values — all [[...]] template variables and CSS custom properties
5. HTML theme guide — complete build walkthrough with full source

Then:

• Theme app-card integration — card-style and button-style broadcast protocol
• Theme settings — expose settings to the profile owner dashboard
• Theme dev preview — test with live data before uploading

---

Before Release

• App package checklist — required files and image dimensions
• Release checklist — privacy, security, and submission requirements
• Troubleshooting — common errors and fixes

---

Documentation Structure

Section	What it covers
Platform Overview	What Shuuka owns vs what builders own, the core contract
Build an App	Everything from quickstart to admin pages and storage
Build a Theme	Everything from HTML templates to card style broadcasting
Reference and Release	Checklists, troubleshooting, and submission
Downloads	Starter packages