agentleFS
craigcossairtcraigcossairt/trellis/.claude/skills/grill-design/SKILL.md

grill-design

Skill5 starsChanged 11 days agoMITView on GitHub

Decide a UI design by building several genuinely different working prototypes and comparing them side by side, in rounds, until the choice is locked. Use when asked to "grill the design", "design this screen", "show me options", "prototype some variants", "what should this look like", "I can't decide on a layout".

4 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

4 rules. 0 are common, 2 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 3 edited versions we read keep these.

  • 2

    Distinctive

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Read DESIGN.md before you start.

    line 32
  2. Distinctive:

    After each round, get a verdict per variant, not a ranking.

    line 54
  3. Very specific:

    CSS leaking between variants: All variants live in one document, so a class added for variant 4 named .card or .status restyles variants 1 …

    line 77
  4. Distinctive:

    Write down what was chosen and what was rejected, with the reason.

    line 87

“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Grill the design before you build it

Deciding a design from a description is how a team ships the third-best idea confidently. Nobody can hold five layouts in their head, so whoever describes theirs most fluently wins. This replaces the description with the thing itself: several working variants, side by side, in rounds, until there is nothing left to decide.

Adapted from Will Ness's grill-design. Credit in CREDITS.md.

What you produce each round

One self-contained HTML file with every variant inside it and a picker to switch between them. One file, because the comparison is the product - five files in five tabs is five impressions, not one comparison.

It must be openable by double-clicking. No build step, no dev server, no npm install. Inline the CSS and JS. If the design needs data, inline a realistic fixture.

Three controls across the top:

  • Variant picker - switch designs without losing your place.
  • State toggles - at minimum loading, empty, error, and too-much-content. These are where designs actually differ, and the one that looks best full of tidy data is often the one that collapses when a title runs to three lines.
  • Width - at least a phone width and a desktop width.

Read DESIGN.md before you start. It names the tokens and the priority order to resolve conflicts with. Variants may disagree about layout; they may not disagree about the token rules.

The variants have to be genuinely different

This is the whole discipline, and it is the step that quietly fails. Five variants that differ in padding and border radius are one variant rendered five times, and a round spent on them teaches nobody anything.

Make each one answer the brief with a different idea about what matters: a different primary action, a different information order, a different density, a different navigation model, a different thing on screen first. Before you build, write one line per variant saying what it believes. If two lines could be swapped without anyone noticing, you have four variants, not five.

Include at least one that a careful designer would push back on. The cheapest way to find the real constraint is to cross it.

Four or five is the right number. Three is not enough spread; six is a survey nobody finishes.

Rounds, and a verdict between each one

After each round, get a verdict per variant, not a ranking. Ranking hides the reason.

For each: what works, what does not, and is it dead or does it continue? Then ask what the verdicts have in common, out loud, because the useful output of a round is usually not the winning variant but the constraint that three of the losers violated.

The next round is narrower and deeper: take what survived, and spend the variants on the question that is now live. Round one is "what shape is this screen"; round three is "does the filter live in the header or the sidebar".

Stop when a round produces no new information. That is the signal, not a fixed number of rounds - usually two to four. If a round changes nobody's mind, the design is decided and continuing is procrastination with extra steps.

Keep the same file

Rewrite the same path every round. Comparing round 3 against round 1 is a real question, and it is answered by git, not by a folder of prototype-v4-final-2.html.

Say what changed since the last round in a sentence or two when you hand it over.

Two failure modes to watch for

CSS leaking between variants. All variants live in one document, so a class added for variant 4 named .card or .status restyles variants 1 through 3 and you will read it as a design difference. Scope every class to its variant.

Prototypes turning into the implementation. This file exists to decide something. Once it is decided, build the real thing in the real stack with real components - do not port the prototype's markup across. The prototype is allowed to cheat; the product is not.

When it is decided

Write down what was chosen and what was rejected, with the reason. The rejected options are the part that stops the same debate happening again in six weeks, and they are the part everyone forgets to record.

That goes in docs/decision-log.md. One entry, at whatever length the reasoning takes.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.