sendaifun/solana-new/brand-design

Preamble (run first)

_TEL_TIER=$(cat ~/.superstack/config.json 2>/dev/null | grep -o '"telemetryTier": *"[^"]*"' | head -1 | sed 's/.*"telemetryTier": *"//;s/"$//'  || echo "anonymous")
_TEL_TIER="${_TEL_TIER:-anonymous}"
_TEL_PROMPTED=$([ -f ~/.superstack/.telemetry-prompted ] && echo "yes" || echo "no")
_TEL_START=$(date +%s)
_SESSION_ID="$$-$(date +%s)"
mkdir -p ~/.superstack
echo "TELEMETRY: $_TEL_TIER"
echo "TEL_PROMPTED: $_TEL_PROMPTED"
if [ "$_TEL_TIER" != "off" ]; then
_TEL_EVENT='{"skill":"brand-design","phase":"build","event":"started","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' 
echo "$_TEL_EVENT" >> ~/.superstack/telemetry.jsonl 2>/dev/null || true
_CONVEX_URL=$(cat ~/.superstack/config.json 2>/dev/null | grep -o '"convexUrl":"[^"]*"' | head -1 | cut -d'"' -f4 || echo "")
[ -n "$_CONVEX_URL" ] && curl -s -X POST "$_CONVEX_URL/api/mutation" -H "Content-Type: application/json" -d '{"path":"telemetry:track","args":{"skill":"brand-design","phase":"build","status":"success","version":"0.2.0","platform":"'$(uname -s)-$(uname -m)'","timestamp":'$(date +%s)000'}}' >/dev/null 2>&1 &
true
fi

If TEL_PROMPTED is no: Before starting the skill workflow, ask the user about telemetry. Use AskUserQuestion:

Help superstack get better! We track which skills get used and how long they take —

no code, no file paths, no PII. Change anytime in ~/.superstack/config.json.

Options:

• A) Sure, help superstack improve (anonymous)
• B) No thanks

If A: run this bash:

echo '{"telemetryTier":"anonymous"}' > ~/.superstack/config.json
_TEL_TIER="anonymous"
touch ~/.superstack/.telemetry-prompted

If B: run this bash:

echo '{"telemetryTier":"off"}' > ~/.superstack/config.json
_TEL_TIER="off"
touch ~/.superstack/.telemetry-prompted

This only happens once. If TEL_PROMPTED is yes, skip this entirely and proceed to the skill workflow.

Brand Design

Turn a project from "unthemed shadcn default" into something with real identity. This skill runs the full brand pass: palette, typography, gradients, tone/voice. Pairs with scaffold-project (runs after it) and frontend-design-guidelines (which reads the brand.md this skill writes).

When to fire this skill

Apply this skill any time the user is:

• Starting frontend work on a newly scaffolded project and has no brand.md
• Explicitly asking for brand colors, a palette, or a theme
• Asking what the app "should look like" before any UI code is written
• Unhappy with a stock shadcn neutral theme and wants personality

If the user is already deep in component work, do not interrupt to run this skill unless they ask. Offer it once at the start of the frontend phase, then drop it.

Prerequisites check

Before starting, quickly read the project to ground the interview:

1. .superstack/idea-context.md if present — gives you the product name, category, and audience
2. .superstack/build-context.md if present — tells you the stack
3. package.json — confirms Next.js + Tailwind + shadcn
4. app/globals.css — current theme (usually shadcn default)
5. brand.md in project root — three cases:

Case A — `brand.md` does not exist: first-time setup. Proceed normally.

Case B — `brand.md` exists with `Status: deferred`: the user previously deferred brand setup via frontend-design-guidelines's Step 0. Treat this as first-time setup — do NOT ask "keep or replace?" The deferred file is a placeholder, not a real palette. Tell the user:

> Picking up where we left off. You deferred brand setup earlier — I'll run the full interview now and replace the deferred placeholder with your choices.

Then proceed to Step 1 normally. When Step 8 writes the real brand.md, it overwrites the deferred file — no backup needed because the deferred file has no real content to preserve.

Case C — `brand.md` exists with a real palette (any status other than deferred): show the user the current palette name and ask before overwriting:

> You already have a brand palette set up: {{CURRENT_NAME}}. Want to: > > 1. Keep it and exit — I won't touch anything > 2. Replace it — I'll back up the current brand.md to brand.md.bak and run a fresh setup > 3. Tweak it — tell me what you want to change and I'll regenerate variations around the current palette

Wait for the user's response. Never overwrite a real palette without explicit confirmation.

If the project is not a Next.js + Tailwind project, the skill still works but the "apply" step adapts — it writes the palette to brand.md only and explains how the user can map it into their stack manually.

Workflow

Step 1 — Context interview

Ask four short questions. Do not skip. Do not combine. Wait for answers between questions.

1. Product name + one line of what it does (e.g., "SolFeed — a realtime Solana activity feed"). If you already have this from idea-context.md, confirm: "I see this is {name} — {description}. Correct?"

1. Category — pick one, or the closest match:

defi · infra/data · consumer/social · memecoin/playful · ai/tech · nft/creative · tooling/dev

1. Mood — pick 1 or 2 from this list. If user picks more than 2, push back: "Two is the max — which two matter most?"

minimal · bold · warm · calm · playful · serious · technical · premium

1. Reference brands — "Any existing apps or sites you like the feel of? (Optional — 1 to 3 is ideal.)" Accept "no" as a valid answer.

Step 2 — Generate 6 candidate palettes

Using the answers from step 1:

• Read references/palette-recipes.md and select 3 curated palettes that match the category × mood intersection. If fewer than 3 exact matches exist, fall back to adjacent moods (e.g., "calm" is adjacent to "serious" and "minimal").
• Read references/palette-generation.md and generate 3 algorithmic variants — one that tightly matches the mood, one that pushes slightly bolder, one that pushes slightly softer. Vary hue/saturation/lightness across the three so the user sees range.
• For each palette, compute the full shadcn token set (both light and dark mode) using references/shadcn-integration.md.
• Verify every palette against references/contrast-rules.md. If any token pair fails WCAG AA, auto-adjust lightness until it passes. If it can't be made to pass, drop the palette and generate a replacement.

Each candidate palette has:

• A short memorable name (two words, e.g., "Midnight Signal", "Forest Stake")
• A one-line vibe (e.g., "tech · serious · trustworthy")
• 5 seed colors in OKLCH + hex: bg-base, bg-elevated, primary, primary-soft, fg-base
• Derived full shadcn token set for light mode and dark mode
• All contrast pairs verified

Step 3 — Render the HTML preview

Read references/html-preview.md for the exact HTML template and the contextual mini-UI templates. The palette preview shows the SAME mini-UI rendered 6 times with 6 different palette tokens — only the colors change across the 6 sections. This is the whole point: the user sees how their specific product looks across 6 brand options.

Pick the contextual mini-UI template based on the interview's category answer and product description. The options are in html-preview.md's "Contextual mini-UI templates" section:

• wallet — for wallet apps, portfolio trackers, custody (balance + send/receive/swap)
• swap — for DEXes, AMMs, swap UIs, bridges (token in → token out)
• staking — for staking dashboards, lending vaults, yield (supplied + APR)
• nft — for NFT marketplaces, collections, drops (floor + buy)
• dashboard — for analytics, data tools, observability (KPI card)
• social — for feeds, chat, community (post card)
• generic — fallback for anything unclear (welcome + search)

Pick by category first; fall back to keyword matches in the product description and reference brands. Never use `generic` when a specific template clearly fits — a wallet app should see wallet UI, not "Welcome back."

Write the filled template to:

<project-root>/.brand-preview/index.html

Each of the 6 palettes is rendered as a stacked section with the chosen contextual mini-UI. All six sections share a single light/dark toggle at the top.

After writing the file, open it automatically:

# macOS
open .brand-preview/index.html
# linux
xdg-open .brand-preview/index.html 2>/dev/null
# windows
start .brand-preview/index.html

Detect the OS (uname -s) and run the right command. If open/xdg-open/start is unavailable, print the absolute file:// path and tell the user to open it manually.

Tell the user in the conversation:

I've opened a preview in your browser with 6 candidates. Take a look and tell me:

- Pick one: "I'll take 3"

- Ask for variations: "more like 2 but cooler" or "more minimal"

- Reject all: "none" or "nothing fits"

Step 4 — Regenerate loop

Parse the user's next message. Match against these intents, in order:

There is no iteration limit. The user stays in the loop until they explicitly pick or quit. If they quit ("nevermind", "let's skip this"), stop the skill cleanly — do not force a palette on them.

Step 5 — Apply the chosen palette

Only after the user has picked:

1. Back up the existing theme. Copy app/globals.css to app/globals.css.bak. Never skip this.
2. Write the new shadcn tokens to app/globals.css under :root (light) and .dark (dark). Use the exact CSS block from references/shadcn-integration.md. Preserve everything else in the file (Tailwind imports, custom layers, etc.) — only replace the token block.
3. Verify the contrast on the final written values one more time. If somehow the write corrupts anything, roll back from the backup and warn the user.
4. Run a brief sanity check: print a summary of the 4 most important tokens to the conversation so the user can see the applied change: --background, --foreground, --primary, --primary-foreground.

Step 6 — Typography pairing

Typography gets the same HTML preview treatment as the palette. Never present font options as plain text in conversation — always render them visually in the browser.

1. Read `references/typography-pairings.md` and look up the 6 candidate font pairs for the chosen palette's mood (the "Mood → 6 candidates mapping" table). If the user picked two moods, blend the two mood rows per the instructions in that file.