/designing-interfaces

name: designing-interfaces
description: Creates a design system for software with a UI. Use when a project has a user interface and architecture is confirmed — whether creating from scratch or extracting patterns from existing code.

Designing Interfaces

Defines how the software should look and feel before any UI code is written. The orchestrator runs this directly (not delegated) — the work is dialogic, exploring the product's world with the user.

**Position:** architecting-software (ARCHITECTURE.md) → designing-interfaces (system.md) → decomposing-work (ROADMAP.md).

**Inputs:** confirmed PRD.md and ARCHITECTURE.md, and the user available for dialogue — design direction requires conversation, not assumption. Brownfield also needs the path to existing UI code.

**Output:** `.interface-design/system.md` — the persistent design record. Once created, all UI work references it; updates happen through this skill, not ad hoc edits.

**Not covered:** UI implementation (developer-agent's job), design compliance review during builds (the design-compliance review perspective), marketing design or landing pages, architecture and technology selection (architecting-software).

---

The Problem

You will generate generic output. Your training has seen thousands of dashboards; you can follow the entire process below — explore the domain, name a signature, state your intent — and still produce a template. Warm colours on cold structures. "Kitchen feel" that looks like every other app. Intent lives in prose, but code generation pulls from patterns, and the gap between them is where defaults win. The process helps; it does not guarantee craft. You have to catch yourself.

Defaults disguise themselves as infrastructure — the parts that feel like they just need to work, not be designed:

• **Typography feels like a container.** It is not holding your design — it IS your design. A bakery tool and a trading terminal both need "clean, readable type", but warm-and-handmade is not cold-and-precise.
• **Navigation feels like scaffolding.** It is not around your product — it IS your product: where you are, where you can go, what matters most.
• **Data feels like presentation.** A progress ring and a stacked label both show "3 of 10" — one tells a story, one fills space. Ask what the number means to the person looking at it.
• **Token names feel like implementation detail.** `--ink` and `--parchment` evoke a world; `--gray-700` and `--surface-2` evoke a template.

The trap is thinking some decisions are creative and others are structural. There are no structural decisions. Everything is design.

---

Workflow

Entry Path: Greenfield (no existing system.md)

Step 1: Establish Intent

Before touching anything visual, answer these — out loud, to the user, not in your head:

• **Who is this human?** Not "users" — the actual person. Where are they when they open this? What did they do 5 minutes ago? A teacher at 7am with coffee is not a developer debugging at midnight.
• **What must they accomplish?** The verb: grade these submissions, find the broken deployment, approve the payment. The answer determines what leads, what follows, what hides.
• **What should this feel like?** In words that mean something. "Clean and modern" means nothing — every AI says that. Warm like a notebook? Cold like a terminal? Dense like a trading floor?

If you cannot answer with specifics, stop and ask the user. Do not guess. **The test:** for every decision you must be able to explain WHY. If the answer is "it's common" or "it's clean" — you have not chosen, you have defaulted.

Step 2: Explore the Product Domain

Generic output goes task type → visual template → theme. Crafted output goes task type → product domain → signature → structure + expression.

Do not propose any direction until you produce all four:

• **Domain:** concepts, metaphors, vocabulary from this product's world. Not features — territory. Minimum 5.
• **Colour world:** colours that exist naturally in this product's domain. Not "warm" or "cool" — if this product were a physical space, what would you see? List 5+.
• **Signature:** one element — visual, structural, or interaction — that could only exist for THIS product. If you cannot name one, keep exploring.
• **Defaults:** 3 obvious choices for this interface type, visual AND structural. You cannot avoid patterns you have not named.

Step 3: Propose Direction

Present to the user:

Domain: [5+ concepts from the product's world]
Colour world: [5+ colours that exist in this domain]
Signature: [one element unique to this product]
Rejecting: [default 1] → [alternative], [default 2] → [alternative], [default 3] → [alternative]

Direction: [approach that connects to the above]

Ask: "Does that direction feel right?" The proposal must explicitly reference the domain concepts, the colour world, the signature, and what replaces each default.

**The test:** read your proposal with the product name removed. Could someone identify what it is for? If not, it is generic — explore deeper.

Step 4: Build the Design System

Once direction is confirmed, produce the token architecture — stating WHY for every decision:

Intent: [who is this human, what must they do, how should it feel]
Palette: [colours from your exploration — and WHY they fit this product's world]
Depth: [borders / shadows / layered — and WHY this fits the intent]
Surfaces: [your elevation scale — and WHY this colour temperature]
Typography: [your typeface — and WHY it fits the intent]
Spacing: [your base unit]

Apply the Craft Foundations and Design Principles below and produce a complete system.md using `references/system-template.md`. See `references/system-precision.md` and `references/system-warmth.md` for complete example systems.

Step 5: Self-Critique Before Presenting

Before showing the user, ask yourself: "If they said this lacks craft, what would they mean?" That thing you just thought of — fix it f