diff --git a/README.md b/README.md index 6055f26..9428793 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,18 @@ One service, many contexts. The same card renders in your GitHub README, dev.to A community gallery for sharing single-card presets and adopting others' designs as a starting point is in progress — see Roadmap below. +## About this project + +**Currently implemented.** 28 SVG card endpoints (`/api/*`), 17 built-in themes plus gist-hosted custom palettes via `theme_url=`, five bundled variable fonts, `/api/stack` composition with namespaced child IDs, a live playground at [profilekit.vercel.app](https://profilekit.vercel.app), and an MCP wrapper at [`@heznpc/profilekit-mcp`](https://www.npmjs.com/package/@heznpc/profilekit-mcp). Zero runtime dependencies, 30-minute CDN cache, deployed on Vercel. + +**Planned.** A single-card preset gallery at `/gallery` — adopt someone else's design URL as a starting point, then tweak parameters in the editor. Cross-agent preset compile (one preset → Claude Code, Cursor, Codex CLI configs). `theme_url=` adoption across the rest of the catalog. + +**Design intent.** *No ranking, composable presentation.* Each card is a parameter-only URL — every visual property exposed as a query string so the same endpoint renders in a GitHub README, a dev.to bio, a Hashnode header, or a slide cover with no template forking. The gallery is for *adoption*, not voting: you start from someone else's preset and edit it; we do not show which preset is "most popular." Pure SVG with CSS / SMIL keeps animations alive inside GitHub's image proxy and removes the JavaScript attack surface. + +**Non-goals.** No ratings. No rankings. No leaderboards. No remix lineage / fork trees. No raster fallback for upload-only platforms (LinkedIn, Discord, X, Medium) — export to PNG yourself if you need one; we will not pretend the SVG works there. No tracking pixels, no per-view analytics. + +**Redacted.** None. +

diff --git a/docs/design/PROMPT-FOR-DESIGN-TOOL.md b/docs/design/PROMPT-FOR-DESIGN-TOOL.md new file mode 100644 index 0000000..df3e173 --- /dev/null +++ b/docs/design/PROMPT-FOR-DESIGN-TOOL.md @@ -0,0 +1,439 @@ +# UI prototype: ProfileKit v3 Composer + +You're redesigning the visual + interaction layer of a three-pane editor. +The data model, JavaScript, design tokens, and a working-but-ugly reference +implementation are all included in this single file. **Nothing is attached +separately. Everything you need is below.** + +Return one self-contained HTML file (vanilla HTML/CSS/JS, no build step, +no external libraries except a CDN font if you really need one). Reuse the +JavaScript at the bottom of this brief verbatim — only the markup and CSS +need to change. + +--- + +## 1. What ProfileKit is (30 seconds) + +ProfileKit is a customizable SVG card service for GitHub READMEs and +similar surfaces (Notion covers, Hashnode banners, dev.to bios). 28 cards +(hero, stats, languages, pin, snake, matrix, terminal, …), every visual +property exposed as a `?query=parameter`. Cards render at +`https://profilekit.vercel.app/api/?…` and are dropped into a +README via `` or `` tags. + +Stated ethos: **"no ratings, no rankings — just clean, customizable cards."** + +The existing playground has two tabs: + +- **Cards** — pick one card, tune its params with a live SVG preview, copy + the URL. +- **Templates** — curated picks; click "Load" to copy a preset into the + Cards editor. + +You are designing **a third tab: Compose.** + +--- + +## 2. What you're building + +A **README composer**. The user assembles an entire README — multiple +cards plus markdown blocks — instead of just configuring one card at a +time. Mental model: + +- **Sims 3 Create-A-Style** (UX reference, not brand): pick parts from an + inventory, drop them on a canvas, tune slots in an inspector. +- **Naver blog skin editor**: slot pre-built widgets into a layout, then + configure each one. + +Two layers, both swappable: + +1. **Intra-card slots** — each card declares its own slots + (`bg`, `name`, `theme`, `font`, …); the user fills them. +2. **Inter-card composition** — the README is an ordered list of + blocks (`card` or `markdown`); the user adds, reorders, removes. + +The output is a README markdown snippet where each card is wrapped in a +`` element with a `prefers-color-scheme` source pair, so the +result auto-respects the reader's OS theme. + +--- + +## 3. MVP scope (locked) + +Only `hero` has slot declarations and a real inspector this round. The +other 27 cards still appear in the inventory and still render — they just +use endpoint defaults until v3.2 ships their slot decls. + +| In scope | Out of scope (later milestones) | +|---|---| +| Three-pane editor (inventory, canvas, inspector) | Drag-from-inventory (v3.3) | +| Click-to-add blocks | Inline edit on the preview itself (v3.4) | +| Reorder via ↑↓ buttons | URL-share for full compositions (v3.1) | +| Hero slot inspector | Slot decls for the other 27 cards (v3.2) | +| Markdown blocks (passthrough textarea) | Backend / gallery / accounts (v4) | +| Composition defaults: theme + font | Ratings / rankings / remix lineage (永 — never) | +| `` dark/light pair output | | +| `localStorage` persistence | | + +--- + +## 4. Layout + +``` +┌────────────┬──────────────────────────┬──────────────┐ +│ INVENTORY │ COMPOSITION │ SLOT │ +│ ~240px │ fluid │ INSPECTOR │ +│ │ │ ~340px │ +│ Composition│ [hero card preview] ⌃⌄ │ │ +│ Blog │ ## Foundation ⌃⌄ │ bg: ▼ wave │ +│ · hero │ [pin card preview] ⌃⌄ │ name: ___ │ +│ · section │ │ theme: ▼ … │ +│ Data │ [Clear] [Copy markdown] │ font: ▼ … │ +│ · stats │ │ width: 1200 │ +│ Animations │ │ height: 280 │ +│ · matrix │ │ ─────────────│ +│ · snake │ │ Composition │ +│ │ │ defaults │ +│ │ │ theme: ▼ … │ +│ │ │ font: ▼ … │ +└────────────┴──────────────────────────┴──────────────┘ +``` + +Responsive: + +- ≤ 1080px → 2 columns (inspector wraps under the canvas as a full-width + bottom strip). +- ≤ 720px → 1 column (inventory becomes a horizontal scrolling chip strip + at the top; inspector becomes a bottom sheet that opens on selection). + +--- + +## 5. Visual direction + +**Make it feel like a tool a designer would actually use.** Reference +products: + +- **Linear** — pacing of inventory · canvas · inspector, the way selection + state and chrome melt away. +- **Vercel dashboard** — chip + table + side-panel pattern, monochrome + with a single accent. +- **Raycast extension store** — inventory tiles, badges, hover states. +- **Figma right-panel** — inspector information density without clutter. + +**Hard aesthetic rules:** + +- Match the existing playground's surface. A user moving between Cards and + Compose should feel one product, not two. Use the design tokens in §6 + unless you have a specific reason to refine a value. +- Dark mode is primary. Ship a `prefers-color-scheme: light` variant. +- One accent color (`--accent`). No competing accents. +- Sharp 6–8px radii, 1px hairline borders, generous whitespace. +- Mono font for parameter values, URL previews, and code-shaped data. +- Animations only on meaningful state changes (selection, drag, copy + toast). 120–180ms ease-out. **No idle motion.** No shimmer, no pulses, + no breathing. + +**Anti-patterns (these read as "AI-generated UI"):** + +- Inline emoji decorations. +- Gradient backgrounds on hero text. +- Frosted glass / glassmorphism. +- Drop shadows on every surface. +- Skeuomorphic raised buttons. +- Multiple competing accent colors. +- Decorative SVG curlicues in empty states. + +**Interaction details that matter:** + +- The empty canvas is what 90% of users see first. Make it inviting and + instructive without preaching. A nudge toward `hero` ("try this first, + it's the MVP") is appropriate. +- Block selection must be obvious from a glance — not a 1px border-color + flip. Linear uses a left accent rail; Vercel uses a subtle background + bump. Pick one and commit. +- Inspector empty state should look intentional, not missing. A small + illustration is fine; an apologetic paragraph is not. +- The "Copy README markdown" CTA is the success moment. Primary button + + a clean modal with the output. Linear's command-palette modal is a + great reference for the modal aesthetic. + +--- + +## 6. Design tokens (use these — already shared with the existing playground) + +```css +:root { + --bg: #0d1117; + --surface: #161b22; + --surface-2: #1c222b; + --surface-3: #232a35; + --border: #21262d; + --border-strong:#30363d; + --text: #e6edf3; + --muted: #8b949e; + --muted-2: #6e7681; + --accent: #58a6ff; + --accent-soft: rgba(88, 166, 255, 0.12); + --warn: #d29922; + --danger: #f85149; + --radius: 8px; + --radius-sm: 5px; + --mono: ui-monospace, "SF Mono", Menlo, Consolas, monospace; + --sans: -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif; +} +``` + +For the light variant, derive matched tokens (don't invent a new palette). +The accent stays `#58a6ff` (GitHub blue) in both modes. + +--- + +## 7. Data model & JavaScript (paste verbatim into your file) + +This is the entire data + behavior layer. Wire your new HTML to it via the +IDs/classes referenced inside (or rename the selectors and update the JS +accordingly — your call). Don't change the data shape, the URL builder, +the markdown serializer, the storage key, or the slot decl format — +those are downstream contracts the v3.1+ milestones will read. + +```html + +``` + +--- + +## 8. Output format example + +For a composition `[hero(name=Ren, bg=wave) → markdown("## Foundation") → pin(repo=ProfileKit)]` +with composition defaults `{ theme: "tokyo_night", font: "space-grotesk" }`, +the Copy markdown button must produce exactly this: + +```html + + + + hero card + + +## Foundation + + + + + pin card + +``` + +`compositionToMarkdown()` in §7 already does this — call it from your +copy button and you're done. + +--- + +## 9. Deliverable + +A single HTML file. It must: + +1. Open straight in a browser (`file://` or static server) — no build, no + npm install, no bundler. +2. Render real card images from `https://profilekit.vercel.app/api/...` + so previews are live. +3. Persist composition state to `localStorage["profilekit.composition.draft"]` + exactly as the JS in §7 does (so reload preserves the user's work). +4. Pass a basic visual review at 1440 × 900, 1024 × 768, and 390 × 844. +5. Use the design tokens in §6. + +--- + +## 10. Hard non-goals + +- Don't redesign the Cards or Templates tabs. Compose is additive. +- Don't add a backend, account system, ratings, rankings, remix lineage, + or marketplace. The ethos is *"no ratings, no rankings."* +- Don't change the `/api/*` endpoints or the SVG output. +- Don't modify the data shape, URL builder, markdown serializer, or + storage key in §7. Those are downstream contracts. +- Don't introduce brand language like "human craft layer" or "Sims 3 CAS + for devs" — Sims is a UX reference internally, not customer-facing copy. +- Don't add idle motion, shimmer, pulses, glassmorphism, gradient text, + emoji decorations, or competing accent colors. diff --git a/docs/design/v3-composer.html b/docs/design/v3-composer.html new file mode 100644 index 0000000..f2277ab --- /dev/null +++ b/docs/design/v3-composer.html @@ -0,0 +1,1147 @@ + + + + + + ProfileKit — v3 Composer (design mockup) + + + + + +
+
+

ProfileKit

+

v3 Composer — design mockup (CAS-style README composer)

+
+
+ + + +
+ MVP scope C · hero only +
+ +
+ + + + +
+

Composition

+

Reorder with ↑↓. Click a block to edit its slots on the right.

+ +
+ No blocks yet + Click an inventory item on the left to start composing.
+ Try hero first — it's the MVP scope. +
+ + + +
+ + + + Saved locally · 0 blocks + +
+
+ + + +
+ +
Copied
+ + + + + +