set-dashboard

name

set-dashboard

description

Build the gated dashboard UI (stage 4) of a web app whose backend already works (see set-app-backend). Reads project specifics from PROJECT.md, studies the wired design tokens and reference sites, then builds the full-screen app shell (left sidebar + user block + dropup), the interactive weekly calendar with create/edit/delete entry modals, the shared glassmorphic settings/billing modal (3/5 × 3/5, centered, its own sub-sidebar), and a live streaming AI-chat view with per-user calendar context — all consuming the backend stage's endpoint + server-helper contracts. STOPS at a design-language gate before building and does a visual self-review after. Engineered to defeat generic "AI dashboard" output. Touches only the gated route + its components — never schema, env, lib clients, enforcement, or the marketing route.

Set Dashboard — the gated app UI, on top of a working backend

This skill builds only the dashboard (stage 4). It assumes set-app-backend already made the seams real: requireUser() / getBillingState(), the primary-entity CRUD + presign + chat + Stripe endpoints, and the typed 402 bodies. Earlier stages laid the foundation, the landing page, and those backend contracts; this skill is the last app surface before deploy.

Mental model: the foundation was correctness of seams; the backend was correctness of money and limits; the landing was taste, once. This skill is taste under interaction — the place where the product stops being endpoints and becomes something a person lives inside daily. The failure mode here is the generic admin panel: a boxy sidebar, a data-table dump, three stat cards, a modal that's just a centered white rectangle. This skill's real job is to defeat that — to make the calendar, the modals, and the chat feel like this product (its style adjectives, its palette, its voice), calm and considered, not a bootstrapped CRUD template.

---

Step 0 — Load the brief & verify BOTH prior contracts (required first)

1. Read ./PROJECT.md: identity, one-liner, style adjectives, reference sites, palette, fonts, plans table, and the primary entity's shape. Wherever this skill says "per the brief," read it from PROJECT.md — never invent it.
2. Verify the design foundation (from set-project-structure): the gated route exists (e.g. src/app/dashboard/) with its component dir (src/components/dashboard/); design tokens are wired (palette + --sidebar-* tokens + body/display fonts via next/font); shadcn/ui is initialized. Reuse the landing's visual language where it exists (e.g. components/landing/weekly-calendar.tsx as the calendar's starting vocabulary).
3. Verify the backend contract (from set-app-backend): requireUser(), getBillingState(), the primary-entity CRUD endpoints, /api/assets, /api/chat, /api/stripe/checkout|portal, the logout action, and the typed 402 shapes. If these are missing, stop and tell the user to run set-app-backend first. This skill builds UI; it does not wire backend, edit schema/env, or touch enforcement.

---

Operating principles (apply throughout)

1. Defeat the default. The enemy is the generic dashboard. Every decision traces to the brief (adjectives, palette, voice) or the reference sites — not to an admin-template reflex. Boxy grids, stat-card rows, and centered-white-rectangle modals are tells; avoid them.
2. Consume, never re-implement. All data and mutations go through the backend stage's contracts. Never re-check quota, re-derive plan, presign, or call the LLM from the client — the server owns those. The UI renders state and dispatches intent; it enforces nothing.
3. Handle every state. Loading, empty, error, and the typed 402 are first-class, not afterthoughts. Quota-exhausted must route the user to upgrade/top-up (open Billing); a failed mutation must never look like success. Optimistic UI must roll back on failure.
4. Motion serves hierarchy. Modals, dropups, entry placement, and streaming text animate with restraint, and always honor prefers-reduced-motion. Calm beats busy.
5. Accessible by construction. Modals and the dropup are real dialogs/menus (focus trap, Esc, aria-*, return focus), the calendar is keyboard-navigable, contrast meets AA. Use Radix/shadcn primitives rather than hand-rolled divs.
6. Stay in your lane. Additive only. Touch the gated route and components/dashboard/*. Never edit schema, env, lib/ clients, enforcement routes, the gate file, or the marketing route.
7. Ship-complete in one pass. Every pass leaves a complete, usable dashboard — all views built, all states handled, no TODO/lorem/half-styled sections. The human-iteration checkpoint raises the ceiling; it does not finish unbuilt work. If low on effort, cut a feature cleanly (e.g. attachments) rather than ship a broken one.

---

Procedure

1. Load brief & verify contracts

Per Step 0 — both the design foundation and the backend seam.

2. Study the reference & the wired language (don't just "get inspired")

• Re-open the brief's reference site(s) (Chrome tools if available; else fetch + reason from markup) and read the landing page you already shipped — the dashboard must feel like the same product, not a different app bolted on. Extract concrete decisions: spacing rhythm, type scale, how restrained the color use is, the calendar vocabulary already established.
• Read the wired tokens in globals.css (palette, --sidebar-*, radii, fonts) and use them as-is. Do not invent a parallel token system.

3. Produce the design-language note + view/interaction IA

A short artifact (≈10–14 lines) turning the brief's adjectives into numbers and committing to the interaction model:

• Shell: sidebar width, nav item rhythm, where the user block sits, how the dropup emerges.
• Calendar: the weekly (Mon–Sun) grid — column proportions, how an entry cell reads (dot color from the brand palette, time, title in the display font), how a day's empty area invites a click, week-nav affordance, today emphasis.
• Entry modal: create vs edit; the fields (per the entity shape); how the color picker, time, and duration read; where delete lives; how the live quota state and the 402→upgrade path appear.
• Settings/Billing modal: the shared glassmorphic surface — its exact sizing (≈3/5 viewport width × 3/5 height, centered), the glass recipe (translucency + blur + hairline border), the left sub-sidebar (Settings | Billing) and what each pane shows.
• AI chat: the streaming view — message rhythm, how assistant text settles in, where remaining tokens show, empty-state prompt.
• Motion stance & the banned-patterns you're avoiding.

4. Gate — STOP and wait (before building)

Present and wait for explicit approval. Build nothing until approved. Show:

1. What you took from the reference site(s) + the shipped landing + the wired tokens.
2. The design-language note + view/interaction IA (§3).
3. The glassmorphism recipe and the modal sizing math.
4. Motion plan and the banned-patterns list you're honoring.
5. Which backend contracts each view consumes (so the seam is explicit).
6. Anything you're unsure about or assuming.

5. Build (only after approval)

Build under the gated route with a server layout that reads the user + billing state once and passes it down (export const dynamic = 'force-dynamic'). One component per concern in components/dashboard/*:

• App shell / sidebar. Full-screen flex; fixed left sidebar using --sidebar-* tokens with nav items — Calendar (active) · Actions (coming soon) (visibly disabled, not a dead link) · AI Chat. At the bottom, a user block: the gravatar identicon (gravatarUrl(email) from lib/avatar.ts), name, email. Clicking it opens a dropup (menu emerging upward) with Settings · Billing · Logout — Settings/Billing open the shared modal on the right tab; Logout calls the backend logout action.
• Weekly calendar (primary view). Interactive Mon–Sun grid evolving the landing's weekly-calendar vocabulary: week navigation (prev / next / today), entries placed per day (dot color = bg-brand / bg-brand-orange / bg-brand-brown, time, display-font title). Clicking a day's open area → create-entry modal (that day prefilled); clicking an entry → edit/delete modal. Fetch the visible week's entries server-side (or via the CRUD read); mutations revalidate.
• Entry modal. Create/edit form for the entity's fields (e.g. title, description, color from the three brand dots, start time, duration; optional attachment via /api/assets presign → PUT). Submit → CRUD endpoint; delete → DELETE with confirmation. Show live quota ("3 of 10 this cycle"); on a 402, surface the upgrade/top-up path (open Billing) instead of a raw error.
• Settings/Billing modal (one shared surface). A Radix Dialog, ≈60vw × 60vh, centered, glassmorphic (translucent background + backdrop-blur + hairline border + soft shadow), with a left sub-sidebar (Settings | Billing) and content on the right. Gracefully fall back to full-screen on small viewports. Panes:
  • Settings: profile (identicon, name, email), the referral code + copyable invite link, current plan.
  • Billing: plan card; entry-quota usage (used / limit / resets-at) and AI-token usage (used / budget) from getBillingState(); Upgrade (Pro/Max) and $-top-up buttons → /api/stripe/checkout (redirect); Manage / cancel → /api/stripe/portal.
• AI chat view (separate view via the AI-Chat nav item). A live streaming chat against /api/chat (AI-SDK useChat or equivalent) — the server injects the user's calendar context, so the client just renders the exchange. Assistant text streams in with restrained motion; render markdown safely; autoscroll; show remaining tokens from billing state; empty state offers a starter prompt tied to the calendar. On ai_budget_exhausted 402, route to Billing.

Use the wired tokens as-is; the display font carries headings; images via next/image. Reuse components/ui/ (shadcn) primitives; keep motion behind useReducedMotion().

6. Visual self-review loop (core; degrade gracefully)

• If Chrome tools are available: run the dev server, sign in, and screenshot each surface — calendar, an open entry modal, the glassmorphic settings/billing modal, and the chat — at mobile (~390px) and desktop (~1280px). Critique against the design-language note + the banned-patterns list; fix; repeat until it holds. Verify the glass actually reads as glass over real content behind it (not a flat panel), and the modal sizing is right.
• If browser tools aren't connected: say so, and run the manual review checklist (Definition of Done) by inspection, flagging what you couldn't verify without rendering.
• The dashboard must be complete and usable when this step ends — self-review raises quality, it doesn't finish unbuilt views.

7. Human-iteration checkpoint (raise the ceiling)

Present the rendered result (screenshots or the running URL), a one-line summary of each view, and 2–4 things you're least sure about (e.g. "the glass opacity", "calendar column density", "how the dropup emerges", "chat message rhythm") — invite direct critique, then iterate until the user is happy. "More whitespace / calmer motion / bigger headings" are expected rounds — this is where the polish comes from. If the user says ship it, it stands (it's already complete).

8. Verify & commit

npm run build succeeds; dev server boots; no console errors; no layout shift. Commit as its own clean change on top of the backend baseline. Touch nothing outside the gated route + components/dashboard/*.

---

Banned patterns — actively avoid these tells of AI dashboard slop

• A boxy grey admin-panel sidebar with generic icon+label rows and no relation to the palette.
• A data-table dump or a row of three stat cards as the primary surface.
• A settings modal that's a plain centered white rectangle — "glassmorphic" that's just a solid card with a drop shadow (no real translucency, no blur over content behind it).
• Emoji as nav/feature icons; everything centered; uniform card grids as a crutch.
• Calendar entries rendered as a flat bulleted list instead of living in the day cells.
• Fake data left in the calendar/chat; unhandled empty/error/402 states; a chat that clearly doesn't stream. Motion for its own sake (parallax/float that doesn't serve hierarchy).

If the brief or reference genuinely calls for one of these, justify it. Otherwise, don't.

---

Making it actually beautiful (raise the ceiling)

1. The calendar is the product — give it the display font and room. The week grid, its titles in the display face, generous cell breathing room, and disciplined dot color do more than any chrome.
2. Glass is about depth, not decoration. Real translucency + blur over actual content behind it (the dimmed calendar), one hairline border, a soft shadow — so the modal floats. A solid card with blur classes but nothing behind it is not glass.
3. Restraint with color. Green grounds; orange/brown are sparing accents (a dot, a single CTA), never everywhere. A dashboard that uses its accent constantly has no accent.
4. The dropup should feel physical. It emerges upward from the user block with a short, well-eased transition and correct anchoring — not a menu that teleports in.
5. Coherence with the landing. Someone moving from the marketing page into the app should feel one continuous product — same type, same calm, same palette discipline.
6. Honesty about the ceiling. Say when something is competent-but-not-lovely and surface it at the Step-7 checkpoint. Beauty comes from revision, not one perfect pass.

---

Definition of Done

1. npm run build succeeds; dev server boots; no console errors; no layout shift.
2. Complete & usable in one pass: shell, weekly calendar, entry create/edit/delete modal, shared settings/billing modal, and streaming AI-chat all built and populated — no TODO/lorem/half-styled sections.
3. Consumes the backend contracts only — no client-side quota/plan/presign/LLM logic; all mutations dispatch to the stage-3 endpoints; the typed 402 routes to upgrade/top-up.
4. Sidebar + user block + dropup work (Calendar active, Actions disabled-not-dead, AI Chat; Settings/Billing/Logout wired).
5. Weekly calendar is interactive: day-click creates, entry-click edits/deletes, week nav works, entries live in day cells with brand-dot colors and display-font titles.
6. Settings/Billing modal is one shared glassmorphic surface (~3/5 × 3/5, centered, real translucency+blur, left sub-sidebar), full-screen fallback on mobile; Billing shows entry + AI usage and wires checkout/top-up/portal.
7. AI chat streams with server-injected calendar context and shows remaining tokens.
8. Every state handled (loading/empty/error/402); optimistic UI rolls back on failure.
9. Accessible + responsive: real dialogs/menus (focus trap, Esc, return focus), keyboard- navigable calendar, AA contrast, mobile → desktop; motion honors prefers-reduced-motion.
10. Tokens used as-is (no parallel system); display font carries headings; images via next/image.
11. Visual self-review done (browser loop, or manual checklist with the gap flagged).
12. Nothing outside the gated route + components/dashboard/* was modified.

Out of scope — do NOT build in this stage

Schema/env/lib/ clients/enforcement/webhooks (stage 3 owns them — consume, don't touch); the marketing route (stage 2); deployment (a later stage); the disabled "Actions (coming soon)" feature itself; multi-calendar/team features. The UI renders and dispatches; it never enforces or transacts.

---

Knowledge Appendix — dashboard craft notes

A starting point, not gospel. Re-verify component APIs at runtime; keep versions aligned with what the foundation pinned (no conflicting major of the UI/animation/AI libs).

• Server layout, client leaves. The gated layout.tsx is a server component: requireUser() + getBillingState() once, export const dynamic = 'force-dynamic', then pass state to client components (calendar, modals, chat). Keep data-fetching on the server; interactivity on the client.
• Dropup. A Radix DropdownMenu/Popover anchored to the user block with side="top" (and collision handling) — real menu semantics (focus, Esc, arrow keys), not a toggled div.
• Glassmorphism recipe. Translucent background + blur + hairline border + soft shadow over a dimmed backdrop, e.g. bg-background/60 backdrop-blur-xl border border-border/60 shadow-2xl on a Radix Dialog.Content sized w-[60vw] h-[60vh] (with min/max clamps) and centered; the overlay dims the calendar so the blur has content to blur. Collapse to w-screen h-screen on small screens. Respect reduced-transparency/motion preferences.
• Weekly calendar. Evolve components/landing/weekly-calendar.tsx: seven columns, entries placed in day cells (dot = bg-brand/bg-brand-orange/bg-brand-brown, time, display-font title), a clickable empty area per day, prev/next/today week nav, today emphasis. Fetch the visible range; revalidate after mutations. Keyboard-navigable cells.
• Streaming chat. AI-SDK useChat (or equivalent) → /api/chat; the server injects calendar context so the client sends only the user turns. Stream assistant text with restrained motion, render markdown safely (sanitize), autoscroll to the latest, and read remaining tokens from billing state. On ai_budget_exhausted, open Billing rather than erroring.
• 402 as UX. Treat quota_exhausted / ai_budget_exhausted as a designed moment: a calm prompt that opens the Billing pane with the right CTA (upgrade or top-up), not a red error toast.
• Avatar. gravatarUrl(email) from lib/avatar.ts yields the identicon — no extra network state.
• Motion. Framer Motion for modal/dropup entrances and entry placement — short, well-eased, useReducedMotion()-gated. Motion guides attention (a modal settling, text streaming); it never competes with the calendar.

Reads from the brief: identity/voice (chat + empty-state tone), style adjectives + reference sites + palette + fonts (the whole visual language), plans table (Billing pane), primary-entity shape (calendar + entry modal fields), gated route (where this all mounts).

Depends on set-app-backend for: requireUser(), getBillingState(), primary-entity CRUD, /api/assets, /api/chat, /api/stripe/checkout|portal, the logout action, and the typed 402 shapes. Build against those contracts; never reach past them into schema or enforcement.