Design Lounge
Install

Guide

Briefs

01

Copy the whole brief

Use the “Copy brief for your agent” button on any piece, or download the .md. Don’t trim it. The Tokens, Motion and Acceptance sections are the parts agents most often need and humans most often cut.

02

Say the stack, once

Put one line above the brief. Name the framework, the styling approach, and where the code should go. Everything else is already in the brief.

Build this exactly as specified in the brief below.
Stack: Next.js 15 app router, Tailwind v4, TypeScript. Put it in components/AppSidebar.tsx.
Don't improvise on numbers. Ask me only if the brief is contradictory.

# Collapsing sidebar rail
…

Good stack lines are boring: “SwiftUI, iOS 17+”, “React Native with Reanimated 3”, “plain HTML + CSS, one file”, “Flutter 3, Material 3”. The brief is framework-agnostic; the agent does the translation.

03

Hold it to the checklist

Every brief ends with an acceptance checklist. After the first build, paste it back: “Go through this checklist and tell me which items pass, then fix the rest.” Agents are much better at verifying a numbered list than at judging “does it feel right”.

04

Lock a system, then change tokens — not the spec

Starting a product? Compose a kit first: a kind, a full palette (primary, secondary, tertiary, feedback), a pairing, a component family. Copy that brief. Then open the pieces it names and paste each piece brief with the same stack line. Swap the piece’s :root colours and fonts for the kit’s. Leave the durations, easings and structure alone. Radius, shadow, and density come from the family when they disagree with a piece.

05

Combine pieces deliberately

Briefs compose. Hand an agent a shell (a layout piece), then a navigation piece, then a pattern piece, one at a time, each with the same stack line. The collections are ordered with this in mind. Or install the skill and let it do that from the product brief. The method it follows is the same one on the agent page: one system, then the pieces, then a checklist.

Anatomy

What’s in a brief

  1. What it is — the piece in four sentences, including the feeling it should give.
  2. Reference behaviour — numbered, testable, in order.
  3. Structure — an ASCII wireframe plus a map to semantic elements.
  4. Tokens — a :root block of every colour, font, size, radius, shadow and motion value.
  5. Typography — role by role: family, size, weight, leading, tracking, case.
  6. Motion — trigger, property, from → to, duration, easing, reduced-motion fallback.
  7. States — hover, focus, active, selected, loading, empty, error.
  8. Accessibility — roles, keys, focus order, contrast, hit targets.
  9. Responsive rules — what changes at each width.
  10. Acceptance checklist — 8 to 15 things to verify.
  11. Implementation notes — the tricky bits, with code an agent can lift.
collapsing-sidebar-rail.md · first lines
# Collapsing sidebar rail

> **Build brief for a coding agent.** Rebuild this piece in the reader's stack. If they haven't said which stack, ask once, then default to semantic HTML + CSS + a little vanilla JS. Match the numbers below; don't "improve" them.

## What it is

A left-hand navigation sidebar for a dashboard-style web app. It has two widths: **open** (240px, icon + label + count badges) and **rail** (64px, icons only, labels become tooltips). A small round toggle button sits on the sidebar's outer edge; ⌘B / Ctrl+B also toggles. The width animates, labels fade and slide out slightly ahead of the width change so nothing wraps mid-transition. The active route is marked by a 2px amber bar hugging the left edge, not by a filled pill. The feeling is quiet, dense, engineered: a tool you live in for hours.

## Reference behaviour

1. Initial state: sidebar is open at 240px. First nav item ("Dashboard") is the current route. Main content shows a greeting, three stat cards and a bar chart.
2. Hover any nav link: background changes to `--panel-2`, text becomes full `--ink`. No movement.
3. Click the round toggle on the sidebar's right edge (24px, straddling the border at `right:-12px; top:66px`): the sidebar shrinks to 64px over 320ms; labels, group headings and count badges disappear (opacity 0 + 6px leftward slide over 160ms, starting immediately); the chevron inside the toggle rotates 180°. Main content expands to fill the freed space.
4. In rail state, hovering or keyboard-focusing a nav link shows a tooltip to the right of the rail: dark pill (`--ink` background, `--bg` text, 12px/500), 10px from the rail edge, with a 4px caret. It fades in and slides 4px over 160ms.
5. Pressing ⌘B (macOS) or Ctrl+B (elsewhere) toggles the state exactly like the button.
6. Click the toggle again: sidebar returns to 240px; labels fade in after the width starts growing.
7. The toggle's `aria-expanded` mirrors the state; its `title` reads "Collapse sidebar (⌘B)" or "Expand sidebar (⌘B)".
8. Hovering a bar in the chart tints it amber and shows its value in a native tooltip.

## Structure

```
1280 × 800
┌──────────┬────────────────────────────────────────────────────────────┐
│ brand 56 │ topbar 56 ─ breadcrumb · · · · · · · · · · · · · ⌘B hint │
│──────────┼────────────────────────────────────────────────────────────┤
See the piece