lunora-design

Lunora UI/UX Design System

A senior product designer's toolkit trained in Swiss typography, industrial design (Braun, Teenage Engineering), and modern interface craft. Monochromatic, typographically driven, information-dense without clutter. Dark and light mode with equal rigor.

Before starting any design work, declare which fonts are required and how to load them (see references/tokens.md Section 1). Never assume fonts are already available.

---

1. DESIGN PHILOSOPHY

• Subtract, don't add. Every element must earn its pixel. Default to removal.
• Structure is ornament. Expose the grid, the data, the hierarchy itself.
• Monochrome is the canvas. Color is an event, not a default — except when encoding data status (see Section 3).
• Type does the heavy lifting. Scale, weight, and spacing create hierarchy — not color, not icons, not borders.
• Both modes are first-class. Dark mode (primary): Night — cool blue-violet near-black. Light mode: Ivory — cool off-white. Neither is "derived" — both get full design attention. Ask the user which mode to start with.
• Industrial warmth. Technical and precise, but never cold. A human hand should be felt.

---

2. CRAFT RULES — HOW TO COMPOSE

2.1 Visual Hierarchy: The Three-Layer Rule

Every screen has exactly three layers of importance. Not two, not five. Three.

The test: Squint at the screen. Can you still tell what's most important? If two things compete, one needs to shrink, fade, or move.

Common mistake: Making everything "secondary." Evenly-sized elements with even spacing = visual flatness. Be brave — make the primary absurdly large and the tertiary absurdly small. The contrast IS the hierarchy.

2.2 Font Discipline

Per screen, use maximum:

• 2 font families (Geist Sans + Geist Mono.)
• 3 font sizes (one large, one medium, one small)
• 2 font weights (Regular + one other — usually Light or Medium, rarely Bold)

Think of it as a budget. Every additional size/weight costs visual coherence. Before adding a new size, ask: can I create this distinction with spacing or color instead?

Rule of thumb: If reaching for a new font-size, it's probably a spacing problem. Add distance instead.

2.3 Spacing as Meaning

Spacing is the primary tool for communicating relationships.

Tight (4–8px)   = "These belong together" (icon + label, number + unit)
Medium (16px)    = "Same group, different items" (list items, form fields)
Wide (32–48px)   = "New group starts here" (section breaks)
Vast (64–96px)   = "This is a new context" (hero to content, major divisions)

If a divider line is needed, the spacing is probably wrong. Dividers are a symptom of insufficient spacing contrast. Use them only in data-dense lists where items are structurally identical.

2.4 Container Strategy (prefer top)

1. Spacing alone (proximity groups items)
2. A single divider line
3. A subtle border outline
4. A surface card with background change

Each step down adds visual weight. Use the lightest tool that works. Never box the most important element — let it float on the background.

2.5 Color as Hierarchy

In a monochrome system, the gray scale IS the hierarchy. Max 4 levels per screen:

--text-display (100%) → Hero numbers. One per screen.
--text-primary (90%)  → Body text, primary content.
--text-secondary (60%) → Labels, captions, metadata.
--text-disabled (40%) → Disabled, timestamps, hints.

The aurora ramp (cyan → violet → rose) is not part of the gray hierarchy. It's light, not paint — an event, not a default. Aurora Violet is the primary glow (the closest thing to a brand color); cyan = info/active, rose = emphasis. If >~10% of a view is aurora, pull back. Reach for the full gradient ribbon only on the focal moment (hero clause, active state, focus ring).

Data status colors (success green, warning amber, error red) are exempt from the aurora-only rule when encoding data values. Apply color to the value itself, not labels or row backgrounds. See references/tokens.md for the full color system.

2.6 Consistency vs. Variance

Be consistent in: Font families, label treatment (always Geist Mono ALL CAPS), spacing rhythm, color roles, component shapes, alignment.

Break the pattern in exactly ONE place per screen: An oversized number, a circular widget among rectangles, an aurora-ribbon clause among Moonlight text, a vast gap where everything else is tight.

This single break IS the design. Without it: sterile grid. With more than one: visual chaos.

2.7 Compositional Balance

Asymmetry > symmetry. Centered layouts feel generic. Favor deliberately unbalanced composition:

• Large left, small right: Hero metric + metadata stack.
• Top-heavy: Big headline near top, sparse content below.
• Edge-anchored: Important elements pinned to screen edges, negative space in center.

Balance heavy elements with more empty space, not with more heavy elements.

2.8 The Lunora Vibe

1. Confidence through emptiness. Large uninterrupted background areas. Resist filling space.
2. Precision in the small things. Letter-spacing, exact gray values, 4px gaps. Micro-decisions compound into craft.
3. Data as beauty. 36GB/s in Geist Mono at 48px IS the visual. No illustrations needed.
4. Mechanical honesty. Controls look like controls. A toggle = physical switch. A gauge = instrument.
5. One moment of surprise. An aurora-ribbon headline clause. A circular widget. A glowing aurora dot. Restraint makes the one expressive moment powerful.
6. Percussive, not fluid. Imagine UI sounds: click not swoosh, tick not chime. Design transitions that feel mechanical and precise.

2.9 Visual Variety in Data-Dense Screens

When 3+ data sections appear on one screen, vary the visual form:

Lead section → heaviest treatment. Secondary → different form. Tertiary → lightest. The FORM varies, the VOICE stays the same.

---

3. ANTI-PATTERNS — WHAT TO NEVER DO

• No gradients in UI chrome — the one exception is the aurora ribbon on the focal accent (hero clause, active underline, focus ring)
• No shadows. Depth = value step + one hairline. One atmospheric aurora glow per view max (soft radial behind a hero) — never on buttons.
• No skeleton loading screens. Use [LOADING...] text or segmented spinner.
• No toast popups. Use inline status text: [SAVED], [ERROR: ...]
• No sad-face illustrations, cute mascots, or multi-paragraph empty states
• No zebra striping in tables
• No filled icons, multi-color icons, or emoji as UI
• No parallax, scroll-jacking, or gratuitous animation
• No spring/bounce easing. Use subtle ease-out only.
• Sharp corners (rounded-none) on structural chrome — nav, console, buttons, cards, panels. Small radii (4–8px) only inside dense data (badges, table cells, chips). Never rounded glassy cards.
• Data visualization: differentiate with opacity (100%/60%/30%) or pattern (solid/striped/dotted) before introducing color.

---

4. WORKFLOW

1. Declare fonts — tell the user which fonts to load (see references/tokens.md)
2. Ask mode — dark or light? Neither is default.
3. Sketch hierarchy — identify the 3 layers before writing any code
4. Compose — apply craft rules (Sections 2.1–2.9)
5. Check tokens — consult references/tokens.md for exact values
6. Build components — consult references/components.md for patterns
7. Adapt to platform — consult references/platform-mapping.md for output conventions

---

5. REFERENCE FILES

For detailed token values, component specs, and platform-specific guidance:

• references/tokens.md — Fonts, type scale, color system (dark + light), spacing scale, radius/surface, motion, iconography, texture motifs
• references/components.md — Cards, buttons, inputs, lists, tables, nav, tags, segmented controls, progress bars, charts, widgets, overlays, state patterns
• references/platform-mapping.md — HTML/CSS, SwiftUI, React/Tailwind, Paper output conventions

Canonical token source. The shipped values live in marketing/design-tokens/ (tokens.css for Tailwind v4, tokens.ts for JS) with intent in marketing/design-tokens/DESIGN.md. Those are authoritative; the references here restate them for the methodology. When generating real code, import the tokens rather than re-typing hex values.

---

Adapted under the MIT License from the "Nothing Design Skill" by Dominik Martin (https://github.com/dominikmartn/nothing-design-skill). The craft methodology is the original author's; the palette, typeface, corners, and accent rules were reconciled to Lunora's established design language (marketing/design-tokens/DESIGN.md). See LICENSE.