UI Brief

UI Brief

Tradeoff: Biases toward design opinionation. For greenfield work where the user wants exploration, use claude-design-brief instead.

Produce opinionated, design-leading UI briefs that survive contact with implementation.

The default failure mode for LLM-driven UI work is converging on the same shadcn-default-card-grid for every product. This skill exists to write a brief so opinion-dense and reference-specific that the implementing agent cannot drift back into that default. The output is a standalone Markdown file the user (or an orchestrator + frontend-agent) can paste into a fresh Claude Code session and execute against.

ui-brief vs its siblings. Reach for ui-brief when the deliverable is a written spec to hand to a Claude Code production build; use claude-design-brief instead when you want hi-fi mockups or A/B/C directions drawn on the Claude Design canvas at claude.ai, and frontend-design (or frontend-agent) when you want the UI actually built rather than briefed.

Announce at start: "Using ui-brief to write an opinionated design brief for [project]."

Two Modes — Greenfield vs Rebuild

The skill produces both flavors. Pick the right entry path:

Greenfield (no UI exists yet)

The user is building from scratch. Examples: a new product, a fresh app, a feature with no prior UI surface. The brief sets target style references and primitives upfront — there is nothing to diagnose, only failure modes to anticipate.

Hallmark phrases: "build me a UI for X", "I want to build [thing] and want it to look like [reference]", "design a dashboard for [new product]", "make a frontend for [API/backend that exists]".

Rebuild (UI exists, needs replacement)

The user has a working UI that buries the product's value or feels generic. The brief leads with a diagnosis of the current state, then prescribes the replacement.

Hallmark phrases: "the current UI sucks", "redesign this dashboard", "make this not look like every shadcn admin", "the design feels generic", "rebuild the frontend".

Both modes share most of the brief's structure. The differences:

The opinion density and structure are otherwise identical.

When To Use This vs Other Skills

• ui-brief (this) — produces a brief / spec / prompt. Output is a Markdown file. No code is written.
• ui-ux-pro-max — design intelligence (palettes, fonts, component patterns) consumed during implementation.
• frontend-design — the implementation skill that builds distinctive frontends.
• frontend-agent — the role agent that does the actual building.
• ux-review — reviews a built UI in a real browser. Use after the build/rebuild ships.
• orchestrator — consumes this brief if the build is large enough to need a multi-agent team.

ui-brief (write the spec)
        ↓
orchestrator + frontend-agent (build it)
        ↓
ux-review + playwright (verify it)

If the user has only a vague idea ("I want a better dashboard but I do not know what for"), invoke brainstorming first, then come back here with the spec it produces.

What Makes A Good Brief

The briefs that work follow a specific shape. Each section earns its presence:

1. The Opening — Greenfield: state the vision and the target reference language up front. Rebuild: name what is wrong with the current UI vividly, referencing the screenshot file.
2. The Thesis — extract the product's actual moat in one paragraph. Every design decision will be evaluated against it.
3. Design Language — concrete reference points appropriate to the domain. Examples of the shape: Linear × Notion × Arc for a productivity tool; Stripe × Vercel × Posthog for a developer marketing site; bento-grid × glassmorphism × claymorphism for a playful consumer product; Datadog × Grafana × Linear for ops tooling. Pick what fits — never copy-paste these. State both positive references AND negative references — what to actively avoid is at least as load-bearing as what to emulate. Greenfield briefs lean into target styles; rebuild briefs often lean against the failure mode.
4. Hard Rules — 8–12 numbered, opinionated rules. Anchor numbers (32px row height, 2s pulse, 60/40 split). Frame them as judgment-cementing starting points, not laws.
5. Page-by-Page Brief — every primary route gets a layout treatment with what belongs and what does not.
6. Component Primitives — name 8–12 reusable pieces with implied APIs (e.g. <MetricNumber>, <DenseTable>).
7. Motion / Sound / Notifications — usually missing from briefs; including this section prevents drift toward over-animation or zero animation.
8. Accessibility & Responsive Baseline — explicit, not aspirational. axe AA, specific viewports (default 375 × 667 mobile + 1440 × 900 desktop), mobile-first with min-width queries, the canonical breakpoint tokens (sm/md/lg/xl/2xl), no hardcoded width: <px> on layout containers, no inline style= for layout. These are contract clauses for the implementing agent — see skills/roles/frontend-agent/references/mobile-responsive.md for the playbook they will execute against.
9. Implementation Discipline — which skills compose during the build (brainstorming → orchestrator → frontend-agent → playwright → ux-review).
10. Definition of Done — verifiable items. Must include "loads in a browser with zero console errors" and a screenshot-diff item (vs old screenshot for rebuilds, vs target reference for greenfield). And — whenever the product's moat depends on live data, a real service, or an integration — a "the moat is real" item that exercises the actual value path end-to-end against the real thing once (a real call, real data flowing), not a mock of it. The whole brief leads with the moat (§2); a DoD that only checks render + screenshots is a DoD a mock can satisfy, and a mock-satisfiable DoD ships a fiction — a "watch real LLMs compete" product that never calls an LLM, a live dashboard wired to a fixture. Mocks are the right way to build the UI before the backend lands; the DoD's job is to force graduating from them. If the brief deliberately scopes the backend out, mark it a SHELL spec in one line at the top — so a green shell is never mistaken for a finished product.
11. Notes for the Operator — guardrails to prevent drift back to generic defaults during the build.

The voice matters. Brief bullet points and bare specifications produce bland UIs. Opinion-dense paragraphs with rationale produce good ones. Explain the why for every non-obvious decision.

How To Run

Step 1 — Discovery (2–5 minutes of reading)

Before writing a single line of the brief, ground the work in the actual project. Generic briefs come from skipping this step.

• Read the README, CLAUDE.md, and package.json. What is the stack? What libraries are already installed? Which ones are barely used? Libraries-already-installed-but-underused is gold — recommending them costs the project nothing and proves you read the file.
• List the routes / pages if any exist yet. find <frontend>/src/app -type d -maxdepth 3 (Next.js) or equivalent for the framework in play.
• List the existing components and hooks. Which primitives already exist that the brief should reuse vs replace?
• Look for screenshots in the repo root or docs/. Use the Read tool on PNG/JPG files — Claude Code can see them. For rebuilds the current UI is the most important artifact you have. For greenfield, look for design mockups, Figma exports, mood-board files.
• For greenfield with no project yet, the user must provide either target reference apps or a written vision. If neither is present, ask one targeted question.

Step 2 — Diagnose or Vision

Rebuild mode — answer two questions in writing (your own scratch, before the brief):

1. What is wrong with the current UI? Be specific. "Generic" is not a diagnosis — why is it generic? Same visual weight on every section? Hero card hides the product? No information density? Wrong chart library for the domain? Cards on a navy background that looks like every B2B SaaS panel from 2023?
2. What is the product's actual moat? Read the README's "core thesis" / "what is this" section, the marketing copy, the CLAUDE.md. Reduce to one sentence. The brief's hero element will be whatever makes this moat visible.

Greenfield mode — answer two different questions:

1. What is the product's actual moat or differentiator? Same question, different source — read the plan, the brainstorm, the user's vision. The hero element will surface this.
2. What is the target style language? From the user's stated references, the product's gravity (playful vs serious vs operational), and the space (consumer vs prosumer vs operator). State it in 2–3 reference apps + 1–2 named styles drawn from the design intelligence vocabulary (ui-ux-pro-max recognizes 67 styles — pick from there: bento-grid, glassmorphism, claymorphism, neumorphism, brutalism, minimalism, skeuomorphism, etc.).

If you cannot answer the moat question from the project's own files, ask the user one targeted question — do not guess. The whole brief hangs on this answer.

Step 3 — Pick References

Choose 2–3 positive references and 2–3 negative references. Concrete apps/products and named styles, not adjectives.

For greenfield with target styles already stated by the user (e.g. "I want bento-grid item cards, glassmorphism trust badges, dark mode default"), lean into them — they are the brief's design vocabulary, not the failure mode. Negative references in greenfield mode usually call out the adjacent failure modes (the generic version of what they are asking for).

These tables are starting points, not laws. Pick what fits the product's gravity. Always include negatives — naming what to avoid is half the brief's job.

Step 4 — Write The Brief

Use references/brief-template.md as the structural skeleton. Do not fill it in mechanically — the template is a checklist of sections, not a template for the prose. Each section needs project-specific opinion density.

File location: by default, write to <repo-root>/UI-CHALLENGE.md. If UI-CHALLENGE.md already exists, name the next one UI-CHALLENGE-v2.md. The user can rename. For greenfield builds embedded inside a larger build challenge, the UI brief may be a section of a larger document (like THE-GAUNTLET.md) rather than a standalone file — ask the user if unclear.

Length: typically 200–350 lines of Markdown. Short enough to paste into a fresh session, long enough to be opinion-dense. Ruthlessly cut sections that do not earn their keep — but do not cut for length alone.

Step 5 — Verify Before Returning

Before reporting done, check:

• The brief mentions 2+ libraries already installed in the project (proves discovery happened, where applicable).
• The brief has both positive AND negative reference points (proves opinion).
• The DoD includes "loads in a browser with zero console errors" and a screenshot-diff item — vs old screenshot for rebuilds, vs target reference / mockup for greenfield.
• If the moat depends on live data / a real service / an integration, the DoD has a "the moat is real" item that exercises the real path once (not a mock). If the brief is deliberately UI-only, it declares itself a SHELL spec at the top.
• The brief lists which skills should compose during the build.
• The brief is under 400 lines (or you have a defensible reason for going longer).

Then summarize for the user in 3–5 sentences: the diagnosis-or-vision, the chosen references, where the brief lives. Show, do not narrate.

Anti-Patterns

Output File Convention

The brief is a standalone Markdown file. It must be paste-ready into a fresh Claude Code session. That means:

• Self-contained — no "see [other doc] for X." If a referenced doc is critical, inline its key points.
• Project-specific — references the actual stack, the actual routes (or the planned ones), the actual screenshots or target references.
• Operator-aware — includes a "Notes for the Operator" section for guardrails during build.
• Skill-coverage list at the end — which skills should fire during the build (so the operator can audit coverage after).

Examples Of Briefs That Worked

Two reference briefs are linked from this skill's parent repo (when running inside the Skill Madness context):

• Greenfield — THE-GAUNTLET.md at the Skill Madness repo root. Single-prompt greenfield stress test for "Bazaar" (eBay × PayPal × Twitter). Called for bento-grid item cards, glassmorphism trust badges, dark-mode default, full responsive. The UI section is one phase of a larger build brief — the design language was opinion-dense even without an existing UI to diagnose.
• Rebuild — UI-CHALLENGE.md at the MarketsBeRigged repo root. Diagnoses the existing trading dashboard's "generic shadcn admin grid" failure mode and prescribes a Bloomberg × Linear × TradingView replacement that leads with the LLM-reasoning moat.

Both followed the structure above. Read them when in doubt about voice. The greenfield one shows how to lean into target styles; the rebuild one shows how to diagnose and replace.