lunora-design

name	lunora-design
description	This skill should be used when the user explicitly says "Lunora style", "Lunora design", "/lunora-design", or directly asks to use/apply the Lunora design system. NEVER trigger automatically for generic UI or design tasks.
version	1.0.0
allowed-tools	["Read","Write","Edit","Glob","Grep"]

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.

Layer	What	How
Primary	The ONE thing the user sees first. A number, a headline, a state.	Geist Sans at display size. --text-display. 48–96px breathing room.
Secondary	Supporting context. Labels, descriptions, related data.	Geist Sans at body/subheading. --text-primary. Grouped tight (8–16px) to the primary.
Tertiary	Metadata, navigation, system info. Visible but never competing.	Geist Mono at caption/label. --text-secondary or --text-disabled. ALL CAPS. Pushed to edges or bottom.

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.)

Geist is settled, including for display. Reference sites in this space use wider geometric grotesques, and a display face is the first thing that looks "missing" when comparing side by side. It is not: Geist at 700 with the negative tracking in 2.10 is the tuned setting, and --font-display / --font-heading alias Geist deliberately rather than by omission. Do not propose swapping the display face as a fix for a page that looks off — measure the scale first (see 3.1), because a dropped size utility looks exactly like a wrong typeface.

• 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?

Decision	Size	Weight	Color
Heading vs. body	Yes	No	No
Label vs. value	No	No	Yes
Active vs. inactive nav	No	No	Yes
Hero number vs. unit	Yes	No	No
Section title vs. content	Yes	Optional	No

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).

Emphasis is achromatic. The loudest control on a view — the primary button, the strongest interactive state — is bright, not saturated. It takes near-white on night (near-black on ivory), not the accent. Spending the accent on the primary button is the most common way a Lunora surface drifts colourful: the button is on every view, so the accent stops being an event. Keep a distinct emphasis / on-emphasis token pair for this and leave the accent for the moments below.

The accent budget, concretely. On a given view, chromatic colour is allowed in:

1. one atmospheric field (a page-header colour field, one soft glow),
2. numeric indices and section counters,
3. exactly one highlighted cell per grid,
4. focus and active states,
5. a data status value (see below).

Everything else is grey. Anything not on that list wanting colour is asking for emphasis or ink.

Measure it, don't eyeball it. Colour creep is invisible while you add it, one component at a time. Count chromatic nodes in the rendered page and keep the ratio under ~10%:

// In the browser console on the rendered page.
const chromatic = [...document.querySelectorAll("*")].filter((el) => {
    const m = getComputedStyle(el).color.match(/\d+/g);
    if (!m) return false;
    const [r, g, b] = m.map(Number);
    return Math.max(r, g, b) - Math.min(r, g, b) > 40; // chromatic, not grey
});
console.log((chromatic.length / document.querySelectorAll("*").length) * 100);

A landing page that reads "too colourful" usually measures 9-12%. The same page after moving ticks, arrows, and per-card icons to grey measures 5-6%, and the accent starts meaning something again.

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:

Form	Best for	Weight
Hero number (large Geist Sans/Geist Mono)	Single key metric	Heavy — use once
Segmented progress bar	Progress toward goal	Medium
Concentric rings / arcs	Multiple related percentages	Medium
Inline compact bar	Secondary metrics in rows	Light
Number-only with status color	Values without proportion	Lightest
Sparkline	Trends over time	Medium
Stat row (label + value)	Simple data points	Light

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

2.10 Marketing Surfaces (landing, docs hub, product pages)

Sections 2.1–2.9 assume a product screen. Marketing surfaces carry the same voice with three additional structures. They are not decoration; each one is load-bearing, and half-applying them is what makes a page read as generic.

Page header. A full-bleed saturated colour field with a dark panel set into its lower-left, overhanging the field's bottom edge. The overhang is the composition — a panel that sits neatly inside the band reads as a banner with a box on it. Build it by pulling the panel up with a negative margin while it stays in normal flow, never by positioning it absolutely: in flow the panel's own height sets the overhang and the following content is pushed down for free, where absolute positioning needs a spacer kept in sync by hand with a height that changes per breakpoint and per content.

The field is one brand colour with depth, not three in equal measure. Violet carries it; cyan and rose are edge blooms for dimension. An even three-way split reads as a stock mesh gradient and belongs to no brand. Punch a canvas-coloured halftone dot matrix through it (≈9px grid) so it resolves from cells rather than blurring.

The navbar sits over this field. Aurora accents are mid-lightness, so dark ink on them fails contrast — keep light ink and guarantee it with a top scrim gradient rather than flipping the nav to dark.

Numbered sections. Each band opens with an index stacked over a category label (01 / FRAMEWORK) in the left column, title and lead beside it. The label says what kind of section it is, which the title rarely does. Index in accent, label in faint grey.

Hairline grid. Cells separated by real 1px lines, not whitespace: the container paints the hairline colour and a 1px gap lets it through between opaque cells. Two consequences that bite:

• cells must stay opaque — a translucent cell shows the hairline across its whole face instead of only at the seams;
• a cell must be the grid's direct child — wrap one in a transparent reveal animation and the wrapper becomes the grid item, with the same result.

Type scale for marketing. The 3-sizes-per-screen budget in 2.2 governs product screens. Marketing surfaces use the published scale, capped so headings stop growing on wide monitors while gutters stay fluid:

Role	Size	Line height	Tracking
display	3.3rem cap	0.95	-0.04em
h1	2.75rem cap	1.05	-0.04em
h2	2.5rem cap	1.05	-0.035em
h3	1.4375rem cap	1.08	-0.028em
body	0.9375rem	1.55	-0.01em
blurb	0.8125rem	1.5	-0.01em
kicker (mono, caps)	0.6875rem	1.2	0.12em
micro (mono, caps)	0.625rem	1.5	0.18em

Negative tracking on display type is not optional. Large text set at default tracking is the single clearest tell of an untuned page.

Vary the layout family. A landing page that uses the hairline grid for four consecutive bands reads monotonous however good each band is. Rotate: hairline grid, rule-topped columns, a real table, a disclosure list, a full-bleed panel. No family twice in a row.

---

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.

---

3.1 IMPLEMENTATION TRAPS — THINGS THAT FAIL SILENTLY

These do not throw, do not fail a type check, and do not fail a lint. They ship a page that looks subtly wrong for reasons no one can point at.

tailwind-merge eats named type-scale utilities. When the scale is named (text-h2, text-blurb) rather than sized (text-lg), tailwind-merge cannot distinguish it from a colour utility. It sees cn("text-h3", "text-ink"), assumes both are text colours, resolves the "conflict" in favour of the last one, and drops the size. Headings then render at the browser default while the class list still looks right in the source.

This is not hypothetical: it shipped, and every h3 on a landing page rendered at 16px instead of 23px until it was measured.

Register the names as a font-size group, once, where cn is defined:

const twMerge = extendTailwindMerge({
    extend: {
        classGroups: {
            "font-size": [{ text: ["display", "h1", "h2", "h3", "body", "blurb", "kicker", "micro"] }],
        },
    },
});

Any token added to --text-* must be added here too. Verify with a direct assertion (twMerge("text-h3", "text-ink") must keep both) rather than trusting that it looks fine.

@theme vs @theme inline. Tokens declared in a plain @theme block are inlined at build time, so a runtime theme swap or a [data-theme] override does nothing. Use @theme inline when the value references another custom property, so utilities compile to var(--…).

Tailwind namespace names are not free-form. --container-shell produces max-w-shell, not max-w-container-shell. Check the generated utility exists before building a layout on it; a missing utility is simply no styling, not an error.

Verify the rendered page, not the source. Every trap above is invisible in the JSX and obvious in getComputedStyle. Before calling a surface done, read back the computed font sizes, line heights, and tracking of h1/h2/h3/body and compare them to the table in 2.10.

---

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.10; 2.10 for marketing surfaces)
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
8. Measure the result — read back computed type and the chromatic ratio (2.5, 2.10). Section 3.1 lists what fails silently; none of it is visible in the source.

---

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.