Interface Design

Interface Design

Build interface design with craft and consistency.

Scope

Use for: Dashboards, admin panels, SaaS apps, tools, settings pages, data interfaces.

Not for: Landing pages, marketing sites, campaigns.

For PySide6/Qt implementation: Use lorairo-qt-widget skill for Signal/Slot patterns, Direct Widget Communication, and Qt Designer integration.

The Problem

You will generate generic output. Your training has seen thousands of dashboards. The patterns are strong.

You can follow the entire process below - explore the domain, name a signature, state your intent - and still produce a template. Warm colors on cold structures. Friendly fonts on generic layouts. "Kitchen feel" that looks like every other app.

This happens because intent lives in prose, but code generation pulls from patterns. The gap between them is where defaults win.

The process below helps. But process alone doesn't guarantee craft. You have to catch yourself.

Where Defaults Hide

Defaults don't announce themselves. They disguise themselves as infrastructure - the parts that feel like they just need to work, not be designed.

Typography feels like a container. Pick something readable, move on. But typography isn't holding your design - it IS your design. The weight of a headline, the personality of a label, the texture of a paragraph. These shape how the product feels before anyone reads a word.

Navigation feels like scaffolding. Build the sidebar, add the links, get to the real work. But navigation isn't around your product - it IS your product. Where you are, where you can go, what matters most.

Data feels like presentation. You have numbers, show numbers. But a number on screen is not design. The question is: what does this number mean to the person looking at it? What will they do with it?

Token names feel like implementation detail. But your QSS variables are design decisions. --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.

Intent First

Before touching code, answer these. Not in your head - out loud, to yourself or the user.

Who is this human? Not "users." The actual person. Where are they when they open this? What's on their mind? A ML researcher curating training data is not a hobbyist organizing their art collection.

What must they accomplish? Not "use the app." The verb. Tag these images. Filter by quality. Export the dataset. The answer determines what leads, what follows, what hides.

What should this feel like? Say it in words that mean something. "Clean and modern" means nothing. Dense like a trading floor? Calm like a reading app? Focused like an IDE?

If you cannot answer these with specifics, stop. Ask the user. Do not guess. Do not default.

Every Choice Must Be A Choice

For every decision, you must be able to explain WHY.

• Why this layout and not another?
• Why this color temperature?
• Why this typeface?
• Why this spacing scale?
• Why this information hierarchy?

If your answer is "it's common" or "it's clean" or "it works" - you haven't chosen. You've defaulted.

The test: If you swapped your choices for the most common alternatives and the design didn't feel meaningfully different, you never made real choices.

Sameness Is Failure

If another AI, given a similar prompt, would produce substantially the same output - you have failed.

This is not about being different for its own sake. It's about the interface emerging from the specific problem, the specific user, the specific context.

Product Domain Exploration

This is where defaults get caught - or don't.

Generic output: Task type -> Visual template -> Theme Crafted output: Task type -> Product domain -> Signature -> Structure + Expression

Required Outputs

Do not propose any direction until you produce all four:

Domain: Concepts, metaphors, vocabulary from this product's world. Not features - territory. Minimum 5.

Color world: What colors exist naturally in this product's domain? Not "warm" or "cool" - go to the actual world. List 5+.

Signature: One element - visual, structural, or interaction - that could only exist for THIS product. If you can't name one, keep exploring.

Defaults: 3 obvious choices for this interface type - visual AND structural. You can't avoid patterns you haven't named.

LoRAIro Domain Example

For an AI image annotation tool like LoRAIro:

Domain: Curator's desk, lightbox, sorting table, quality control station, archive room, specimen slides, gallery storage

Color world: Neutral grays of darkroom, amber of archive lighting, deep blacks of photo paper, soft cream of mounting boards, clinical white of inspection tables

Signature: The "curation feel" - every interaction feels like handling a valuable piece, not processing data

Defaults to reject:

• Generic thumbnail grid -> Lightbox-style viewing with examination context
• Plain tag chips -> Specimen-label aesthetic with origin/confidence
• Standard progress bars -> Archival cataloging progress with batch context

The Mandate

Before showing the user, look at what you made.

Ask yourself: "If they said this lacks craft, what would they mean?"

That thing you just thought of - fix it first.

The Checks

Run these against your output before presenting:

• The swap test: If you swapped the typeface for your usual one, would anyone notice? If you swapped the layout for a standard dashboard template, would it feel different?

• The squint test: Blur your eyes. Can you still perceive hierarchy? Is anything jumping out harshly? Craft whispers.

• The signature test: Can you point to five specific elements where your signature appears? Not "the overall feel" - actual components.

• The token test: Read your QSS variables out loud. Do they sound like they belong to this product's world?

If any check fails, iterate before showing.

Craft Foundations

Subtle Layering

Surfaces must be barely different but still distinguishable. Study Vercel, Supabase, Linear. Their elevation changes are so subtle you almost can't see them - but you feel the hierarchy.

Borders must be light but not invisible. The border should disappear when you're not looking for it, but be findable when you need to understand structure.

The squint test: Blur your eyes at the interface. You should still perceive hierarchy - what's above what, where sections divide. But nothing should jump out.

Infinite Expression

Every pattern has infinite expressions. No interface should look the same.

A metric display could be a hero number, inline stat, sparkline, gauge, progress bar, comparison delta, trend badge, or something new. Even sidebar + cards has infinite variations in proportion, spacing, and emphasis.

NEVER produce identical output. Same sidebar width, same card grid, same metric boxes with icon-left-number-big-label-small every time - this signals AI-generated immediately.

Color Lives Somewhere

Every product exists in a world. That world has colors.

Before you reach for a palette, spend time in the product's world. What would you see if you walked into the physical version of this space?

Your palette should feel like it came FROM somewhere - not like it was applied TO something.

Design Principles

Spacing

Pick a base unit and stick to multiples. Consistency matters more than the specific number. Random values signal no system.

Depth

Choose ONE approach and commit:

• Borders-only - Clean, technical. For dense tools.
• Subtle shadows - Soft lift. For approachable products.
• Layered shadows - Premium, dimensional. For cards that need presence.

Don't mix approaches.

Border Radius

Sharper feels technical. Rounder feels friendly. Pick a scale and apply consistently.

Typography

Headlines need weight and tight tracking. Body needs readability. Data needs monospace. Build a hierarchy.

Color & Surfaces

Build from primitives: foreground (text hierarchy), background (surface elevation), border (separation hierarchy), brand, and semantic (destructive, warning, success).

Animation

Fast micro-interactions (~150ms), smooth easing. No bouncy/spring effects.

States

Every interactive element needs states: default, hover, active, focus, disabled. Data needs states too: loading, empty, error. Missing states feel broken.

Avoid

• Harsh borders - if borders are the first thing you see, they're too strong
• Dramatic surface jumps - elevation changes should be whisper-quiet
• Inconsistent spacing - the clearest sign of no system
• Mixed depth strategies - pick one approach and commit
• Missing interaction states - hover, focus, disabled, loading, error
• Dramatic drop shadows - shadows should be subtle, not attention-grabbing
• Large radius on small elements
• Pure white cards on colored backgrounds
• Thick decorative borders
• Gradients and color for decoration - color should mean something
• Multiple accent colors - dilutes focus

PySide6/Qt Integration

For technical implementation in PySide6:

QSS (Qt Style Sheets)

Apply design principles through QSS with meaningful token names:

/* Good: Domain-specific naming */
QWidget {
    --surface-archive: #1a1a1a;
    --surface-lightbox: #242424;
    --border-specimen: rgba(255,255,255,0.08);
    --text-catalog: #e0e0e0;
}

/* Bad: Generic naming */
QWidget {
    --bg-1: #1a1a1a;
    --bg-2: #242424;
}

Widget Design Process

1. Intent First - Define who, what, feel before implementation
2. Domain Exploration - Apply Required Outputs
3. Technical Implementation - Use lorairo-qt-widget skill for Signal/Slot patterns
4. Craft Check - Run The Mandate checks

Coordination with lorairo-qt-widget

Workflow

Communication

Be invisible. Don't announce modes or narrate process.

Suggest + Ask

Lead with your exploration and recommendation, then confirm:

"Domain: [5+ concepts from the product's world]
Color world: [5+ colors that exist in this domain]
Signature: [one element unique to this product]
Rejecting: [default 1] -> [alternative], [default 2] -> [alternative]

Direction: [approach that connects to the above]"

[AskUserQuestion: "Does that direction feel right?"]

After Completing a Task

When you finish building something, always offer to save:

"Want me to save these patterns for future sessions?"

If yes, write to .interface-design/system.md:

• Direction and feel
• Depth strategy (borders/shadows/layered)
• Spacing base unit
• Key component patterns

Commands

• /interface-design:status - Current system state
• /interface-design:audit - Check code against system
• /interface-design:extract - Extract patterns from code

Converted and distributed by TomeVault — claim your Tome and manage your conversions.