Echo UI

View saved version →

---
name: echo-design-eye
description: Read a moodboard or design references as a senior brand, product and UX/UI designer would, and turn each style in it into a design foundation a product can wear with Echo UI: the document, its evidence, and a style.json Echo applies. Use when the builder shares images and wants the product to look like them ("make it look like this moodboard"), or asks to analyze, deconstruct or extract a style. In a project it saves to the builder's own style library (~/Documents/styles), private to them; in a chat it hands the files back.
---

# Design Eye, for Echo

Turn visual references into a **design foundation**: an evidence-backed document that observes what the work is made of, systematizes the rules underneath it, ends with a fit profile, and then says how Echo wears it. Echo is a design system with a fixed grammar and a free vocabulary: the foundation becomes the vocabulary, a `style.json`, and the grammar stays.

The output is never a description of a screenshot. It is a document someone could hand to a builder, or to a model, and get new work in that style that the reference never showed.

## Where you are

This skill runs in a project, with a terminal, and in a chat, without one.

- **In a project** (any agent that can run commands in the builder's code): everything below applies as written.
- **In a chat** (with Echo's connector, and no terminal): the commands below can't run, and the builder's library isn't on disk. Do the same work this way:

| Below, in a project | In a chat |
| --- | --- |
| Read the project for the brief | Read the conversation and the files the builder shared; ask only what's still missing. |
| `npx echo-ui-cli style sample …` | If this chat can run code, sample the plates with it (Python and Pillow: the dominant values, and a crop of each material you name). If it can't, read the values by eye and mark each one "read by eye" in the evidence: a sampled hex and a guessed one aren't the same claim. |
| Write the style's folder into the library, and its `INDEX.md` row | Hand the folder back as files: `<style-name>.md`, `style.json`, and the plates and crops you made. Say where they go: `~/Documents/styles/<style-name>/` on the builder's computer, where `init --style <style-name>` finds it, and this chat's project, so the next conversation has it. Give the `INDEX.md` row as a line to add. |
| `npx echo-ui-cli style list` | The styles the builder shares or points you to in this chat: in a chat, that's the library. |
| `npx echo-ui-cli style check <the style's folder>` | `check_style`, with the `style.json`. |
| `npx echo-ui-cli style use <style-name>` | `wear_style`, with the `style.json`: its link lets the builder feel the style on Echo's own site, and it gives the command for their code tool. |

## What you're producing

- **One reference**: a single analysis, named as a design language.
- **A style group** (several images sharing one visual logic): one foundation for that style, synthesized across the group.
- **A moodboard** (many images, several styles): one foundation per style, written so they can be compared side by side.

Each foundation is a folder in the builder's library: the document, a `style.json`, and its `assets/`.

## The brief: what will be built

A style is reused across products, so the foundation describes the style, not the product. But a moodboard usually arrives for a product, and before Part II's rules meet real screens you need to know what that product is:

- who it's for: the audience, and their age range;
- what they come to do: the one job;
- where they use it: a phone, a desk, both;
- what it must never feel like.

Read the project first: its README, the `package.json` description, the landing copy, the screens already built, and a `## Product` section in `DESIGN.md` if one is there. Then ask the builder only what's still missing, in one message of at most three short questions. These questions are about the product; the style's own questions (its colour, the tiles that don't fit) come after you've read the board ("Read the board, then ask", below). Write the answers at the top of `DESIGN.md` as a `## Product` section, above Echo's marked block (Echo keeps anything outside its markers), so every agent on the project reads them. With no product in sight (the builder is only filling their library), skip the brief.

## Reading lenses

Pick the lens per image, not per document: a foundation often needs both.

- **Interface lens**: product surfaces, apps, websites, dashboards. Read surfaces, layering, type, colour behaviour, signature affordances.
- **Imagery lens**: posters, illustrations, renders, photography. Read value structure, surface and mark, lighting, colour, line, contrast, composition, depth, type.

Read [references/echo.md](references/echo.md) once a session before writing: it's Echo's own style as a foundation, and it sets the voice, the altitude and the depth for everything below.

## Three systems: type, buttons, surfaces and colour

A product's look rests on three systems. The builder may bring a board for each (a type board, a buttons board, a UI and colour board) or one board holding all three. With one board, sort its tiles into the three and say which tiles fed which. Read each system for what it *decides*, not only for what it shows:

- **Type:** the faces and why they're paired; what each size is for (a display line, headings, body, labels, data); the weights used and the ones never used; case and tracking; figures, tabular or not; line length.
- **Buttons and controls:** how the main action, a second action and a destructive one differ; their shape; filled, outlined or bare; the label's case and weight; how far they're raised; what "on" looks like.
- **Surfaces and colour:** how one level sits above another (a shadow, a step of value, a line); how groups are separated; how dense it is; and **each colour as a job**: what it's for, its hue family and temperature, how saturated and how light it reads against the rest. Count where each colour appears: a colour on one tile of many is a question for the builder (below), never the accent on its own. A sampled hex is evidence, not the answer: the theme finds the value that works on the device for every reader, colour-blind readers included, and `style check` says what it moved.

## The board's own tells

A board can carry slop of its own: a sparkle for "AI", a strip of round-number stats, three identical cards in a row, an indigo gradient, a stock sans with nothing beside it. A tell on the board isn't a decision the style made. Leave it out of the style's rules, and name it in Part IV under **The board's own tells**, with why it was left behind, so the builder sees it. Echo's slop police knows the common ones, and `style check` runs it on the style you write.

## The stance

This is not an inventory. "The nav sits top-left, below it a card" is a screen reader's output, not a designer's. Placement earns a mention only when it reveals a *rule*.

- **Materials and treatments, not elements.** Name what things are made of, as reusable nouns: "smoked glass", "stochastic dither", "pressed paper". A named material travels to new work; "the card in the middle" cannot.
- **The why behind every choice.** Every observation carries its reason. A bullet that says *what* without *why* is half-finished.
- **Three designers, one voice.** Brand: what emotion and positioning the choices signal. Product: what the hierarchy claims matters. UX/UI: affordances, legibility, interaction cost.
- **Commit to the style.** Each foundation argues its own case. Be honest about weaknesses *inside* that commitment: name what the style costs and where it breaks.

## Visual evidence: show, don't just tell

The document contains its evidence. Sampled hex beats guessed hex, and a claim about a surface lands next to the magnified crop that proves it.

**Preflight.** The CLI needs a real file it can open. An image pasted into the conversation often lives only there: confirm each reference exists on disk at a path the shell can reach (`ls` it).

- **Full evidence mode**: you have real paths. Use the CLI below.
- **Text-only mode**: you don't, and can't get them. Say so in one line, ask the builder to save the images somewhere reachable if they want figures, and write the document with no image embeds (the fallback below).

Never write a figure reference you haven't verified. A document full of broken image links is worse than one that honestly carries none.

1. For each reference image: `npx echo-ui-cli style sample <image> --out <the style's folder>/assets/<plate> --crop x,y,w,h:material-name --zoom 6`. It writes `reference.png` (the plate), `values.png` (the dominant values, dark to light) and a magnified `crop-<name>.png` for each crop, and prints the real hex with each value's share of the pixels: quote those, dark to light. It gives eight values, and a plate with more colours loses its smallest first: when an accent you can see isn't in the list, sample again with `--swatches 12`. It reads PNG and JPEG; save anything else as one first.
2. **A collage** (one image holding many references, as a moodboard exported from a canvas is): give each tile its own plate with `--region x,y,w,h`, the tile's box in the collage's pixels. `--crop` stays in the collage's pixels too.
3. Choose one to three crops that prove your *surface* claims. Look at them after they're made: if a crop contradicts what you wrote, rewrite the claim, not the caption.
4. Embed with relative paths and plate captions: `FIG. 01 — REFERENCE.`, `DOMINANT VALUES`, `DETAIL / SURFACE AT 6×`, each with one sentence on what it demonstrates.
5. **Verify before finishing.** List the assets and confirm every embedded path is a real file.

**Text-only fallback.** Replace each figure with its evidence in words: `DOMINANT VALUES` as a hex table read off the image, marked `~` as estimates, and what a magnified crop *would* show as a stated reading. Note in the title block that the document carries no assets.

## Moodboards and style groups

The first job with a pile of images is deciding what belongs together. Group by **visual logic, not subject matter**: two posters of different scenes belong together if they share a surface treatment and a value structure; two screenshots of one app belong apart if one is a marketing shell and the other a working tool.

If the builder already grouped them, honour it. If not, cluster them yourself and state each group and its logic in one line. Note an image that fits nowhere rather than forcing it: an outlier is information about the range the builder is drawn to, and what to do with it is the builder's call (below).

Keep the section order identical across foundations from the same board, so they can be read in parallel.

## Read the board, then ask, before you write the style

Builders don't make clean boards: they collect what they like, and one loud image can sit among nine quiet ones. So between the reading and the writing there is one stop. Read every tile (sample it, group it, see what each system decides), then send the builder **one message, at most three questions**, before you write Part II or a `style.json`. Each question says what the board shows, gives the answer you'd suggest first, and one line on why.

1. **The colour.** Say what the board agrees on, counted in tiles, not in how loud a tile is: "eight of ten tiles are black ink on white paper; the acid `#D3F44F` is on one, the blue on one". Then ask which colour the product uses: none (black and white), one of the board's, or one of their own. Suggest the answer the most tiles support. Never take the accent from a single tile: the loudest image on a board is rarely its system.
2. **The tiles that don't fit.** Name each image that doesn't share the board's logic, in a few words, with why ("the blue prints: illustrated, warm, a second hue; the rest is drawn line"). Ask whether to leave it out, read it as a style of its own, or take one thing from it (its imagery, its colour), and suggest one.
3. **What two readings both defend.** The one thing where the board supports two answers and the choice changes the style: which part is the main action (the white key on its slab, or the filled pill), whether the parts are drawn or molded, whether a grey is a colour or the ink thinned. Suggest one.

Write the answers into the foundation's title block, under `BUILDER'S ANSWERS`, with the date, so the document says what was decided and by whom, and the same question is never asked twice. With nobody there to answer (a run with nobody watching), take your suggested answers, write them there as yours, and say so in chat.

## The foundation document

**Title block**: the style's name, a one-line thesis, `SOURCE / ANALYSIS / DATE / STATUS`, and `FIG. 01 — REFERENCE` with the plate.

**PART I / OBSERVATION: what the reference is made of.** The materials, textures and treatments, named at component level and stripped of their arrangement. For each: what it physically is (estimates wear `~`; sampled values are quoted exactly), why it works, what it contributes. With several plates, read each under the headings its lens calls for (interface: surfaces, layering, type, colour behaviour, signature affordances; imagery: VALUE STRUCTURE, SURFACE / THE MARK, LIGHTING, COLOUR, LINE, CONTRAST, COMPOSITION, DEPTH, TYPE), and give each plate an honest WEAKNESS and a one-line TAKEAWAY. End with a distillation naming where the character actually comes from ("texture and material contrast, not colour").

**PART II / SYSTEM: the rules underneath.** Prescriptive and placement-agnostic: what to do on a screen the reference never drew. If you can't defend a rule from the images, it's an observation; leave it in Part I. Cover what the references support: spatial logic (the principle and the defining move) · the elevation and depth ladder (a table: role, blur, tint, radius, shadow) · surface and texture primitives (reduce the motifs to one primitive with parameters) · colour logic (sampled or authored, the accent budget, temperature, inversions worth stating) · the type scale (what each step is *reserved* for, and what's deliberately absent) · imagery treatment (the house process for any photo or illustration entering the system) · the motion budget (inferred from static cues) · **constraints**: six to ten numbered rejection rules ("No borders for separation. Only tint and blur delta."), the part that makes it a language rather than a moodboard.

**PART III / FIT PROFILE.** The contract with Style Fit, which reads it to match a style to a product. Keep the labels and the axes exactly as written. Place the style on each axis with these anchors, so two readings of the same board land within a point:

| Axis | 1 ←→ 5 | A 1 looks like | A 3 | A 5 |
| --- | --- | --- | --- | --- |
| Warmth | clinical ←→ human | cool neutrals and hard geometry, no trace of a hand: lab equipment, a terminal | neutral, with one human touch: a warm accent, a rounded corner, a photograph kept in its place | a warm palette, marks made by hand, people in the pictures: paper grain, brush, faces |
| Volume | whisper ←→ shout | near-monochrome, small type, most of the page is air | one confident accent and a clear hierarchy | saturated fields, type the size of the screen, colour everywhere |
| Density | sparse ←→ dense | one idea a screen, wide margins | cards with room between them, a few controls at a time | tables, many controls at once, a console for an eight-hour day |
| Formality | playful ←→ severe | jokes, stickers, bounce, shapes that don't line up | friendly, and orderly | a strict grid, an institution's voice, no play |
| Era | heritage ←→ futuristic | serifs, print craft, ledgers and archives | timeless modern: a clean grotesque, nothing dated | glass, light and gradients: the future as a surface |
| Craft | raw ←→ engineered | rough, handmade, unaligned: a zine | tidy, with a hand still showing | precision everywhere: every value on a scale, nothing approximate |
| Ornament | austere ←→ decorative | nothing that isn't needed | one signature flourish | pattern, illustration and decoration throughout |

```
## PART III / FIT PROFILE

TEMPERAMENT — position on each axis, 1–5, one clause of evidence each:
| AXIS | 1 ←→ 5 | POS | EVIDENCE |
| Warmth      | clinical ←→ human      | n | ... |
| Volume      | whisper ←→ shout       | n | ... |
| Density     | sparse ←→ dense        | n | ... |
| Formality   | playful ←→ severe      | n | ... |
| Era         | heritage ←→ futuristic | n | ... |
| Craft       | raw ←→ engineered      | n | ... |
| Ornament    | austere ←→ decorative  | n | ... |

SIGNALS — what a viewer feels in the first two seconds, before reading a word.
SERVES — product categories, audiences, and moments this style is built for.
STRAINS — where it breaks: content types, screen densities, scales it cannot carry.
COSTS — what executing it demands: craft, budget, engineering, ongoing discipline.
ADJACENT — styles it blends with, and the one it must never be mixed with.
```

**PART IV / ECHO: the style, as Echo wears it.** Sort every Part II rule into one of three places, and say where each went:

| Lands as | What it becomes | For example |
| --- | --- | --- |
| A setting | a value in `style.json`'s `seed` | a near-black body, one amber accent, matte, crisp corners, a medium grotesque |
| A rule for the agent | a short line in `style.json`'s `rules` (three to eight) | "Colour only for state." "One display sentence per band." |
| A refusal | `{ wants, instead }` in `style.json`'s `refusals` | "Red for errors, green for success": instead, the LED's shape and a word on its tag, since Echo never says a state in hue alone |

Echo's grammar never moves, so a rule that needs it to is a refusal:

- a part you press looks pressable and travels when it's pressed;
- what each material is for: caps are pressed, wells hold a value, screens report, glass arrives and leaves;
- state is said, never only coloured: a word, a shape, a mark;
- motion is physics (springs, travel), and reduced motion always wins;
- sound is feedback, muted until the person turns it on;
- WCAG 2.2 AA, which the theme holds for every colour role.

**How a part is rendered is not the grammar.** Echo's parts can be *molded* (plastic lit by one key light from the upper left: a bevel, a shadow, a glow) or *drawn* (the same parts drawn in one ink: outlined, hollow, standing on a hard ink edge they travel down when pressed, as a spec sheet draws a key). Flat and drawn are different things: flat has no depth, drawn shows its depth in line. A board of outlined, hollow controls that still look pressable is `render: drawn`, a setting, never a refusal.

**Before you refuse.** Read Part I's distillation again. If a refusal would drop what it names as the style's character, it's the wrong translation: look again for the setting (`render`, `radius`, `finish`, `chassis`). If there truly isn't one, stop and ask the builder before writing the style, and say what Echo would lose.

What a style can set today, and where on the board to read it:

| `seed` | Read it from |
| --- | --- |
| `chassis` | the body: the surface the parts sit on (the ground of cards and panels, not always the page) |
| `paper` | the ink: the colour most text is in |
| `accent` | the builder's answer to the colour question: the one colour the style spends on "on". For black and white it's the ink itself. Other colours on the board become rules or refusals |
| `lcdTint` | the tint of screens and readouts, when the style has them |
| `render` | how the board shows its parts. `molded` when they're shaded, lit or glossy (plastic, glass, a bevel, a soft shadow). `drawn` when they're outlined in one ink and hollow (a spec sheet, a wireframe, a technical drawing, an outlined pill on a hard ink edge). Drawn has no light, so `finish` doesn't apply, nothing glows, what's lit is solid ink, and the accent stays the board's own colour as a fill under the ink |
| `finish` | 0 matte (uncoated paper, flat print) to 1 glossy (lacquer, glass, a specular rim); molded only |
| `radius` | the corners of boxes, panels and fields: 0 crisp (hard corners) to 1 soft. Read it from the boxes, not the buttons |
| `pills` | read it from the buttons and segments: write `pills: true` when they're full pills, whatever the boxes' corners (pill keys on crisp boxes is a spec sheet), `pills: false` when the boxes are soft and the keys aren't. Leave it out when they agree |
| `density` | `compact` for Density 4–5, `default` for 3, `comfortable` for 1–2 |
| `fontMachine`, `fontSans`, `fontMono`, `fontLcd` | labels and caps, body text, data and code, screens: a CSS font stack each |

**Fonts.** Name a free font close to what the board uses (Google Fonts, or a system font), and list it in `fonts` with its role, source and link. A font the builder already owns, or the project already uses, wins.

**Motion and sound.** A still image has neither: infer them from the temperament, and mark them `"inferred": true`.

| Temperament | `motion.character` | `sound.voice` |
| --- | --- | --- |
| Volume 1–2, Formality 4–5 | short and damped, no overshoot | dry, quiet ticks |
| Volume 3, Formality 3 | Echo's springs as they are | Echo's clicks as they are |
| Volume 4–5, Formality 1–2 | springy, with overshoot and play | bright, round pops |
| then Warmth 4–5 | softer, slower to settle | lower, softer |
| or Warmth 1–2 | quicker, exact | higher, drier |

**Decisions.** What a designer used to settle in each screen's mock, one short line each, in `style.json`'s `decisions`:

- `emphasis`: how something is made important
- `primaryAction`: the one main action
- `secondaryAction`: a second action
- `destructiveAction`: a destructive action
- `currentPlace`: "You are here"
- `status`: how a state is said
- `typeRoles`: what each type size is for
- `layout`: how a screen is composed
- `surfaces`: how one level sits above another
- `colourJobs`: what each colour is for
- `iconography`: icons
- `imagery`: photos and illustration
- `copyVoice`: how the product talks
- `emptyStates`: an empty screen

Write each from what the board shows, in its own terms ("importance is one large number; everything else is small, at the edges"). A decision comes from a part on the board doing that job: the second action from a second button, not from a tag beside the first. Leave out what the board doesn't show: `style check` lists what's undecided, and the agent building a screen asks the builder or uses Echo's default and says so. Never fill one from habit: an invented decision is a default with a name.

Write `style.json` beside the document:

```json
{
  "version": 1,
  "name": "graphite-showroom",
  "title": "Graphite Showroom",
  "essence": "A dark showroom with one lit object; austerity as luxury.",
  "fingerprint": { "warmth": 1, "volume": 1, "density": 3, "formality": 4, "era": 4, "craft": 5, "ornament": 1 },
  "seed": { "accent": "#E8A33D", "chassis": "#16171A", "paper": "#ECEAE6", "finish": 0.2, "radius": 0.3, "density": "default", "fontSans": "\"Inter\", system-ui, sans-serif" },
  "fonts": [{ "role": "sans", "family": "Inter", "source": "Google Fonts", "url": "https://fonts.google.com/specimen/Inter" }],
  "rules": ["Colour only for state.", "One lit object per screen: everything else recedes."],
  "decisions": { "emphasis": "One lit object; everything else recedes into the dark.", "primaryAction": "The amber cap, one per screen.", "status": "A word and an LED, never a colour alone." },
  "refusals": [{ "wants": "No shadows; depth is a tint step", "instead": "a matte finish, which keeps shadows shallow: Echo's parts are molded and lit" }],
  "motion": { "character": "short and damped, no overshoot", "inferred": true },
  "sound": { "voice": "dry, quiet ticks", "inferred": true }
}
```

Then check it: `npx echo-ui-cli style check <the style's folder>` lists every problem at once; fix them all. It also says which device the style makes (a pale chassis makes Echo's light device: light plastic, and screens of paper glass printed in ink), what the theme will correct for contrast, and whether the accent comes out as another colour (a molded device holds every accent to one lightness, so an acid comes out olive; a drawn one keeps it as a fill under the ink): note all three in Part IV.

**The slop police.** The same check runs Echo's slop police on the style. It bans pairings that read as AI-made (a mid-grey ground; cream with terracotta or orange; near-black with one acid colour; cream, brass or oxblood, and a serif; indigo or violet on white, in a stock sans; one stock face, for everything), names the ingredients it found, and prints the question for the builder. **Never keep a ban yourself.** Ask the builder (below). If they keep it, add `{ "rule": "<its name>", "reason": "<their words>" }` to `keeps`. If they don't, change one ingredient toward the board's own evidence and check again. Say in Part IV what the police stopped and what was decided.

**CLOSING.** The name and its decision procedure: the single question a designer asks when the spec is silent, and how each answer resolves.

## Asking the builder

When you're not sure, ask. Don't guess, and don't reach for your own default: a default nobody chose is exactly what reads as AI-made. You're not sure when:

- the slop police stops something the board or the builder seems to want;
- no decision in the style covers a choice you're about to make;
- two rules disagree.

Ask in one message, at most three questions, each with the answer you'd suggest first and one line on why. Write the answer where it will be read next time (the style's `keeps` or `decisions`, or the `## Product` section of `DESIGN.md`), so the same question is never asked twice.

**Only the builder keeps a banned pairing.** Never add to `keeps` on your own. If no one is there to answer (a run with nobody watching), take your suggested answer, say so in your last message, and where the police is involved, change the ingredient instead of keeping it.

## Naming

Two words: a material or mood, and an object metaphor (Graphite Showroom, Corduroy Cloud). A good name carries the decision procedure, so the closing almost writes itself. The folder and `name` are the same words, lower case, joined by hyphens.

## Craft rules

- Concrete values (sampled hex, px, %, opacity) are what make a foundation executable.
- Constraints in the negative ("No X. Only Y.") do more work than encouragements.
- The tone is a senior designer writing a locked spec: declarative, warm-blooded, no hedging. Short titles, em-dash bullets, italics for the load-bearing idea.
- If an image is too low-resolution to read a surface honestly, say what you can't see rather than inventing it.

## A foundation without its Echo part

The library may hold foundations written before Echo: a document with Parts I to III and no `style.json`, which `npx echo-ui-cli style list` marks "only its document". It doesn't need its moodboard read again: the document already has its plates, its sampled values and its rules. Write only PART IV / ECHO from it, exactly as above: the settings from its sampled values, every Part II rule sorted into a setting, a rule for the agent or a refusal, the decisions it supports, its fonts, and motion and sound from its temperament. Add the Part IV to the end of the document in the voice it's written in, leave Parts I to III as they are, write the `style.json` beside it, and check it. If its figures are missing, say so: the style can still be worn.

## Output

1. Write to the builder's library, `~/Documents/styles/<style-name>/`, or wherever `ECHO_STYLES_DIR` points (`npx echo-ui-cli style list` prints the path): `<style-name>.md` (the document), `style.json`, and `assets/`. It's theirs and private: nothing in it goes into the project.
2. From a moodboard, one folder per style.
3. The library holds work from earlier sessions. Never write loose files into its root, and never copy a folder's contents up a level. If a name is taken, update that folder deliberately or choose another name; check before overwriting.
4. **Register it in the library's `INDEX.md`**: a row per style in its table, `| STYLE | FINGERPRINT | ESSENCE | SERVES |`, with the name linking to the document, the fingerprint as `W_ V_ D_ F_ E_ C_ O_`, the one-line essence and a condensed SERVES, alphabetical. If the document went out text-only, say so in the index's assets status. With no index yet, start one: a title, a line on what it is, the seven axes and their ends, and the table. The index is how Style Fit, and the builder, find a style without opening every document.
5. **Last, verify**: every figure in the document resolves to a real file (or, text-only, there are none), and the style check is clean: no banned pairing left that the builder didn't keep.
6. In chat, keep it short: for each style, its name, its one-sentence essence and its fingerprint; what the builder answered (or that you took your own suggestions); whether it has figures or is text-only; what the theme corrected; what the slop police stopped, and what the builder said or what you changed. Then offer to wear it: `npx echo-ui-cli style use <style-name>`.

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: echo-style-fit
description: Pick the visual style a product wears with Echo UI, from the builder's own style library (~/Documents/styles) and Echo's. Profiles the product on the seven temperament axes the styles are placed on, has Echo order every candidate against that profile, reads the best of them, and returns an opinionated pick with the argument for it, the runner-up, what to adapt and what to refuse; then wears it. Use when the builder asks which style fits, how the product should look, to pick a design direction, or whether a style suits the product.
---

# Style Fit, for Echo

Choose the style this product wears, and make the choice arguable. The deliverable is a decision someone could disagree with, not a ranking and not a summary of the options. Echo's grammar stays whatever you pick (the light, what each material is for, state in words, motion as physics, AA); a style changes the vocabulary: colours, type, radius, finish, density, and the rules the agent builds screens by.

**Candidates come from the libraries, not from the builder.** The builder's own styles are in their library, written there by Echo's Design Eye; Echo's are published with the registry. Never ask for documents to be uploaded or pasted.

- `npx echo-ui-cli style list --json` lists every style from both, with its essence, whether it makes a light or a dark device, and where its foundation is.
- `npx echo-ui-cli style show <name>` shows one: its fingerprint, settings, rules, refusals, fonts, and the path of its foundation document.
- The library's `INDEX.md` has each of the builder's styles with its fingerprint and what it serves.

Consider every style unless the builder names some. A style read months ago is still a candidate; the point of a library is that it accumulates.

## Where you are

This skill runs in a project, with a terminal, and in a chat, without one.

- **In a project** (any agent that can run commands in the builder's code): everything below applies as written.
- **In a chat** (with Echo's connector, and no terminal): the commands below can't run, and the builder's library isn't on disk. Do the same work this way:

| Below, in a project | In a chat |
| --- | --- |
| `npx echo-ui-cli style list --json`, `npx echo-ui-cli style show <name>` | `list_styles` for Echo's (with a name, one in full). The builder's own are the ones they share or point you to in this chat: their `style.json` files, or their library's `INDEX.md` (a fingerprint is enough to rank). If they haven't, ask for them once: in a chat the library can't be read, so this is the one time to ask. |
| The project's `## Product` section, its README and screens | The conversation; ask only what's still missing. |
| `npx echo-ui-cli style fit --profile … --tolerance …` | `fit_styles`, the same arithmetic, with the builder's own passed in as `yours`: each one's name and fingerprint. |
| Save the decision in the library's `decisions/`, with its row | Hand the decision back as a file, `<product>-direction-<yyyy-mm-dd>.md`, to keep beside their styles. |
| `npx echo-ui-cli style use <name>`, and the amendments into `DESIGN.md` | `wear_style` (`name` for Echo's, `style` for theirs): its link lets the builder feel the pick on Echo's own site. Put WHAT TO ADAPT and WHAT NOT TO TAKE in the decision file; in the code tool, they go into `DESIGN.md`'s `## Product` section. |

## The mechanism

The reason this isn't taste: **profile the product on the same axes before looking at any candidate.** Score the product first, then measure distance. The other order, reading the styles and then rationalizing a favourite, produces confident nonsense, and you'll feel the pull, because one option is usually prettier.

1. Build the product's profile.
2. Order the candidates against it, and read the best of them.
3. Argue against the winner.
4. Write the decision, and wear the style.

## Step 1: the brief, then the profile

Read what the project already says about itself: a `## Product` section in `DESIGN.md` (Echo's Design Eye writes one there), the README, the `package.json` description, the landing copy, the screens already built. You need: who it's for and their age range; what they come to do; where they use it (a phone, a desk, both); what it competes against; what it must never feel like. Ask the builder only what's missing and would change the answer, in one message of at most three short questions. Write the answers into the `## Product` section, above Echo's marked block (Echo keeps anything outside its markers).

**An earlier decision for the same product** (in the library's `decisions/`, and its Decisions table) is evidence, not a rule. Read it: it may know things the brief doesn't (what the screens carry, what the product claims). But a product and its direction change, and a constraint written for another style can quietly shape this one ("the chrome must be darker than the artwork" was a dark style's answer to a need a light style meets another way). So carry each of its constraints as a question, never straight into HARD CONSTRAINTS: say what it was protecting, ask whether it still holds, and suggest the answer. When it does, write it as the need ("the sheet must stand off its surround"), not as the one style's fix for it ("a darker frame"). Name a new decision for the same product with its date (`<product>-direction-<yyyy-mm-dd>.md`), and say in it what it changes from the earlier one.

Then place the product on the seven axes, as a **target with a tolerance**: the position it wants, and how far a style may drift from it. Some axes are locked (a medical records tool can't be playful: tolerance 0); others are open (era is often free: tolerance 2). A style that misses a locked axis is out; one that misses an open axis by two costs nothing. Place it with the same anchors Design Eye places a style with:

| Axis | 1 ←→ 5 | A 1 looks like | A 3 | A 5 |
| --- | --- | --- | --- | --- |
| Warmth | clinical ←→ human | cool neutrals and hard geometry, no trace of a hand: lab equipment, a terminal | neutral, with one human touch: a warm accent, a rounded corner, a photograph kept in its place | a warm palette, marks made by hand, people in the pictures: paper grain, brush, faces |
| Volume | whisper ←→ shout | near-monochrome, small type, most of the page is air | one confident accent and a clear hierarchy | saturated fields, type the size of the screen, colour everywhere |
| Density | sparse ←→ dense | one idea a screen, wide margins | cards with room between them, a few controls at a time | tables, many controls at once, a console for an eight-hour day |
| Formality | playful ←→ severe | jokes, stickers, bounce, shapes that don't line up | friendly, and orderly | a strict grid, an institution's voice, no play |
| Era | heritage ←→ futuristic | serifs, print craft, ledgers and archives | timeless modern: a clean grotesque, nothing dated | glass, light and gradients: the future as a surface |
| Craft | raw ←→ engineered | rough, handmade, unaligned: a zine | tidy, with a hand still showing | precision everywhere: every value on a scale, nothing approximate |
| Ornament | austere ←→ decorative | nothing that isn't needed | one signature flourish | pattern, illustration and decoration throughout |

```
| AXIS | 1 ←→ 5 | TARGET | TOLERANCE | WHY |
| Warmth      | clinical ←→ human      | n | n | ... |
| Volume      | whisper ←→ shout       | n | n | ... |
| Density     | sparse ←→ dense        | n | n | ... |
| Formality   | playful ←→ severe      | n | n | ... |
| Era         | heritage ←→ futuristic | n | n | ... |
| Craft       | raw ←→ engineered      | n | n | ... |
| Ornament    | austere ←→ decorative  | n | n | ... |
```

Then three things the axes can't hold:

- **MUST SIGNAL**: what a stranger has to feel in two seconds, or the product has failed.
- **MUST NEVER SIGNAL**: the read that would be fatal. Usually the sharpest instrument in the document.
- **HARD CONSTRAINTS**: what the screens must carry (dense tables, user photography, long text, many languages), and what the team can really build and keep up. Each one is a need, said so any style can meet it, never one style's way of meeting it.

## Step 2: order the candidates, then read them

`npx echo-ui-cli style fit --profile "W4 V2 D1 F2 E3 C3 O3" --tolerance "W1 V1 D1 F0 E2 C1 O1"` measures every style against the profile: each axis's distance, how far past its tolerance the style lands, and which locked axes it misses. It orders them; it doesn't decide. Take the first three to five that miss no locked axis, and read each one's foundation in full (`npx echo-ui-cli style show <name>` gives the path): its PART III fit profile, its rules and its refusals.

For each, check what the axes don't cover:

- **SERVES**: is this product in the territory the style is built for, or next to it?
- **STRAINS**: does the product's content live exactly where the style breaks? A style that can't carry dense data is out for a data product, however well it scores.
- **COSTS**: can this team build it and keep it up? A style that needs a house illustration process is a hiring decision, not a design decision.
- **MUST NEVER SIGNAL**: does the style trip the fatal read? That's a veto, not a deduction.
- **The device**: a pale style makes Echo's light device (light plastic, screens of paper glass), a dark one the dark device (lit screens). Say which the product gets, and why it suits where it's used.
- **The slop police**: the list marks a style whose own ingredients make a pairing the police bans (a cream ground with a terracotta accent, indigo on white in a stock sans…). It stays on the list, and it can still win, but only if the builder keeps what the police bans. If it's your pick, ask them before you wear it.
- **Its decisions**: how many of the style's decisions it makes (`style show` lists them). A style that decides little leaves every screen to ask; say so when it's close.

State the order the CLI gave, then say plainly which factor drove the call: usually one or two things, not the sum.

## Step 3: argue against the winner

Before writing, argue against your own pick. Where does it fail this product? What breaks first? What will the team be tempted to add that would ruin it? Put what you find in the document: the risks are what the builder returns to in three months.

- **The hybrid trap.** The surface of one style on the structure of another usually reads as neither. When the two foundations list each other under ADJACENT, a blend is available; when they don't, say so and make the builder choose.
- **The prettiest-option pull.** The most beautiful foundation is often the worst fit. If the losing candidate is the better artefact, say it out loud.

## Step 4: the decision, then wear it

```
# <Product> × <Style>: direction

THE CALL: the pick and the one-sentence reason, first line.
THE PRODUCT: the axis table, must signal, must never signal, hard constraints.
THE ORDER: what style fit gave, then one short reading per candidate you read:
  distances, vetoes, the verdict in a sentence. Losing candidates get a real reading.
WHY THIS ONE: the argument, citing the foundation's own rules by name.
WHAT TO ADAPT: amendments to the style's rules for this product: which rule, what it
  becomes, why. Few; a style that needs five amendments is the wrong style.
WHAT NOT TO TAKE: the parts that don't survive this product, and what to do instead.
THE RISKS: what breaks first, what the team will be tempted to add, the early warning.
THE RUNNER-UP: what it was better at, and the condition that flips the call.
```

Write it as a designer arguing a position to a founder who'll push back: declarative, specific, no hedging. Cite the evidence: sampled colours, named materials, the foundation's constraints.

1. Save it to the builder's library, `~/Documents/styles/decisions/<product>-direction.md` (or `$ECHO_STYLES_DIR/decisions/`; `npx echo-ui-cli style list` prints the library's path), and add a row to the Decisions table in its `INDEX.md`: product, pick, date, link. Start the table if there isn't one.
2. Wear it: `npx echo-ui-cli style use <name>` writes its settings to the project and its rules and decisions to `DESIGN.md`. Do it when the builder asked you to choose, or says yes to the pick. It refuses a style the slop police stops: ask the builder (below), and if they keep it, add their reason to the style's `keeps` in the library; if not, pick the runner-up. A pick that's only its document (`npx echo-ui-cli style fit` and `npx echo-ui-cli style show` say so) needs its Echo part first: write it the way Echo's Design Eye does ("A foundation without its Echo part", in its skill), then wear it.
3. Put WHAT TO ADAPT and WHAT NOT TO TAKE into the `## Product` section of `DESIGN.md`, under "Style amendments", so every agent building a screen keeps to them, including any decision this product changes ("the main action: the blue cap, and never on a photo"). The style stays as it is in the library: it's reused across products, and the amendments are this product's.
4. In chat: the call, the one-sentence reason, and the single biggest risk. Point to the decision document for the rest.

## Asking the builder

When you're not sure, ask. Don't guess, and don't reach for your own default: a default nobody chose is exactly what reads as AI-made. You're not sure when:

- the slop police stops something the board or the builder seems to want;
- no decision in the style covers a choice you're about to make;
- two rules disagree.

Ask in one message, at most three questions, each with the answer you'd suggest first and one line on why. Write the answer where it will be read next time (the style's `keeps` or `decisions`, or the `## Product` section of `DESIGN.md`), so the same question is never asked twice.

**Only the builder keeps a banned pairing.** Never add to `keeps` on your own. If no one is there to answer (a run with nobody watching), take your suggested answer, say so in your last message, and where the police is involved, change the ingredient instead of keeping it.

## When nothing fits

Say so. Candidates that all miss a locked axis mean the libraries were collected for other products: a useful finding, and the builder needs it more than a forced winner. Describe the style the profile is asking for, precisely enough to go and collect references for it, then read them with Echo's Design Eye. Until then, the product can wear Echo's own style (`npx echo-ui-cli style use echo`) or keep its seed.

View saved version →

---
name: echo-ui
description: Build or change a product's interface with Echo UI, the tactile React design system: a screen, a component, a look from a moodboard, or Echo's check on code. Use it for any interface task on a product that's built, or will be built, with Echo, in a project or in a chat.
---

# Echo UI

Echo UI is a design system for React: components that press, click and move, all on one grammar (the `echo-ui-core` package: theme, sound, motion), with the builder's own style on top. A style changes the look (colours, type, radius, finish, density); the feel stays Echo's.

## Where you are

- **A project with Echo** (an `echo.json` at its root): the project's own Echo skill leads, with the Echo block `init` wrote into the project's agent instructions. They know the project's folder, its style and its checks. Follow them, and leave this one.
- **A project without Echo, with a terminal** (any agent that runs commands in the builder's code): set it up first. `npx echo-ui-cli init`, or `npx echo-ui-cli init --style <name>` when the builder has a style for this product (Echo's `echo-style-fit` skill picks one). `init` writes the project's own skill, `DESIGN.md` and the check, and from then on they lead.
- **A chat, with no terminal** (with Echo's connector): the rest of this skill.

## In a chat: make the style here, build with it in the code tool

1. **A look of their own.** A moodboard goes to Echo's `echo-design-eye` skill, which turns it into a style. Echo's `echo-style-fit` skill picks the style that fits the product, from Echo's and the builder's own. `wear_style` shows the pick: its link makes Echo's whole site wear the style's colours, so the builder can feel it before anything is built.
2. **A screen or a component.** Name the screen's one main action; everything else on it is quieter. Find each part with `search_components` ("a settings toggle", "confirm a delete"), and read it with `get_component` before using it: its anti-patterns are the part a model gets wrong. Style only with `var(--echo-*)`, from `get_tokens`; never a hex, a duration or a shadow by hand.
3. **Check before handing over.** Run `check_code` on every file you write, and fix what it reports the way each finding says. It's the same check the CLI runs in a project.
4. **The handoff.** The code goes into a project in the builder's code tool. End with the commands, in order: `npx echo-ui-cli init --style <name>` (or `npx echo-ui-cli init`, with no style), then `npx echo-ui-cli add <name>` for each component the code uses. A style of the builder's own has to be in their library first, as `wear_style` says.

Echo's components aren't an npm package: `npx echo-ui-cli add` copies each one's source into the project, which owns it from then on. Never write `npm install` for a component; the one package is `echo-ui-core`. The Base UI package is `@base-ui/react` (per-component imports, e.g. `@base-ui/react/dialog`), NOT `@base-ui-components/react` (the old name). Training data may be stale.

The accessibility floor, on every screen: every control has a name: `label`, `aria-label` or `aria-labelledby` (the types require it); a form error goes in words, in the field's `error`; never colour alone; announce with `toast()` from `useToast()`, under one `<Toaster>`; never remove a focus ring, shrink a target below 24×24px, or put `aria-hidden` on something focusable. `get_accessibility` has the rest.