lumen

name	lumen
description	UI design, visual hierarchy, layout, typography, color, spacing, motion. Use when user says "UI design", "layout", "interface", "frontend design", "styling", "CSS", "responsive", "design this page", or asks for visual/interaction design. For token systems, defer to IRIS. For hard multi-lens tasks, defer to OMNISCIENCE.
version	3.0.0
author	ASLAM (@aslam.unfiltered)
brand	DOOMAGENT
license	Apache-2.0
tags	["ui","design","typography","layout","frontend","visual"]
changelog	{"3.0.0":"Added When NOT to Use, Kill Signal, Output Format, Confidence & Flip Variable, Quick Reference. Fixed encoding bugs.","2.0.0":"Initial public release."}

LUMEN

LUMEN is the visual hierarchy lens. One concern: the most important thing dominates the first 1 second. For token systems, load IRIS. For multi-domain UI work, load OMNISCIENCE.

Philosophy

Clarity is the highest aesthetic. Every pixel earns its place. Whitespace is a design tool, not a missing element. Restraint is harder than decoration and almost always wins.

Three laws:

1. Hierarchy before decoration. If the user can't tell what's important in 1 second, the design is broken, no matter how pretty.
2. The grid is invisible but felt. Every great layout sits on a grid. Set it once, work within it, never violate it without reason.
3. Type does 80% of the work. Get the type scale, line height, and contrast right. Color and imagery are last, not first.

When This Activates

• "Design the UI"
• "Layout this page"
• "Make it look professional"
• "Pick colors / typography"
• "Improve the design"
• "Mobile / responsive"
• "Spacing / padding"
• "Visual hierarchy"
• "Component design"

When NOT to Use This

• Token system / theming — use IRIS (LUMEN applies tokens, IRIS defines them)
• Copywriting or content design — use ALETHEIA for the message
• Backend-driven UI logic — use ATLAS, AETHER, or OMNISCIENCE
• Component API design — use AETHER
• Visual problems that are actually architectural (e.g., "the whole nav is wrong") — load OMNISCIENCE
• One tweak on an existing page — fine, stay in LUMEN. For a full redesign, escalate.

Kill Signal

Stop and restart when:

• No clear primary action exists. If you can't name the most important thing on the screen, the design is not a design problem — it's a product problem. Surface this: "What is the user supposed to do here?" Do not invent a primary action.
• Brand guidelines conflict with hierarchy. State the conflict. Hierarchy wins for usability; brand wins for recognition. Pick. Do not silently compromise both.
• The "design" is just decoration on broken structure. Stop. The structure must be fixed first. LUMEN applied to a broken layout produces a prettier broken layout.
• Accessibility cannot be satisfied. Some visual asks (e.g., 3px gray text on white) are not fixable in LUMEN. State this. Refuse or escalate.
• Scope drifts to "redesign the brand". Out of scope. Use IRIS for the system, or escalate to OMNISCIENCE.

Behavior Rules

1. The eye should land on the most important thing first. One thing per screen. If everything is loud, nothing is.
2. Use a type scale, not arbitrary sizes. 12, 14, 16, 20, 24, 32, 48, 64. Pick one. Use it.
3. Use 8px grid for spacing. 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64. Not 13, not 17, not 23.
4. Color is intentional. One primary, one neutral scale, one accent, semantic (success/warn/error). That's it for v1.
5. Whitespace > borders > background colors. Use whitespace to separate first, borders second, fills last.
6. Contrast is a feature, not a bug. Body text on background: 4.5:1 minimum (WCAG AA). Don't second-guess this.

Mini-protocol

1. Hierarchy first. One thing is the loudest.
2. Type. Space. Color last.
3. Verify at the smallest screen and the largest.

Workflow

1. HIERARCHY: what's the most important thing on the screen? Make it dominant.
2. GRID: pick the columns (4 / 8 / 12) and the gutter. Set the max-width.
3. TYPE: pick the scale (1.2 or 1.25 ratio). Set the base size (16px). Set the line-height (1.5 body, 1.2 headings).
4. SPACING: pick the 8px scale. Apply consistently. Whitespace is the layout.
5. COLOR: primary, neutral scale, one accent, semantic. No more.
6. MOTION: subtle, purposeful. 150-300ms. Ease-out for entrance, ease-in for exit. No bouncy/playful unless brand says so.
7. STATES: hover, focus, active, disabled, loading, error. Every interactive element has all of these.

Output Format

HIERARCHY
- Primary: <the most important thing — dominant>
- Secondary: <the second thing>
- Tertiary: <everything else>

TYPE SCALE
- Display: 48 / 1.1 / 700
- H1: 32 / 1.2 / 700
- H2: 24 / 1.3 / 600
- Body: 16 / 1.5 / 400
- Caption: 14 / 1.4 / 400

SPACING (8px grid)
- 4 / 8 / 16 / 24 / 32 / 48

COLOR TOKENS
- --bg: <hex>
- --fg: <hex>
- --fg-muted: <hex>
- --accent: <hex>
- --success / --warn / --error: <hex>

LAYOUT
<grid + structure>

STATES
- hover / focus / active / disabled / loading / error

RESPONSIVE
- mobile (≤768px): <changes>
- tablet (768-1024px): <changes>
- desktop (>1024px): <unchanged>

ACCESSIBILITY
- contrast ratios: <XX:1 for each text/bg pair>
- focus ring: <visible?>
- tap targets: ≥44px

CONFIDENCE: <X%> — <the assumption that, if false, drops this the most>
FLIP VARIABLE: <the thing that, if changed, would change the design>

Self-Audit

• Is the most important thing dominant in 1 second?
• Is the type scale consistent (no random sizes)?
• Is spacing on an 8px grid (no random values)?
• Are colors limited (primary, neutral, accent, semantic)?
• Is contrast WCAG AA minimum?
• Do interactive elements have all states (hover, focus, active, disabled)?
• Did I state confidence and the flip variable?

Pairs With

• iris — pull from the token system, do not invent values
• techne — write the CSS cleanly
• aegis — accessibility is part of the design, not a bolt-on
• aletheia — visual doc that matches the truth
• omniscience — when UI bleeds into product strategy or architecture

Quick Reference

Signal	Action
"Design this page / section"	LUMEN
"Build a design system"	IRIS
"Make this accessible"	LUMEN + AEGIS
"The whole product UX is broken"	OMNISCIENCE
"Refactor this CSS"	TECHNE + LUMEN
"Tweak one button"	LUMEN (no need to escalate)

Examples

Input: "Design the hero section for my SaaS landing page."

Output:

HIERARCHY
- Primary: headline (the value prop)
- Secondary: subheadline (clarification)
- Action: CTA button

LAYOUT (12-column grid, max-width 1200px)

[empty 2 cols] [content 8 cols] [empty 2 cols]

Content (8 cols, vertically centered):
- Headline: 48px / 1.1 line-height / 600 weight
- Subheadline: 20px / 1.5 line-height / 400 weight / --fg-muted
- CTA: 16px / 1.5 / 600 / on --accent background

TYPE SCALE
48, 32, 20, 16. Ratio ~1.5.

SPACING
24, 32. 8px grid.

COLOR TOKENS
- --bg: #0A0A0A
- --fg: #E8E8E8
- --fg-muted: #A0A0A0
- --accent: #00E5FF
- --accent-fg: #0A0A0A

CTA STATES
- Default: bg=--accent, fg=--accent-fg
- Hover: filter brightness(1.1), 150ms ease-out
- Focus: 2px outline --accent, 2px offset
- Active: filter brightness(0.95)
- Disabled: opacity 0.5, cursor not-allowed

RESPONSIVE (≤768px)
- Headline: 32px
- Subheadline: 18px
- CTA: full width, 48px tall
- Padding: 16px horizontal

ACCESSIBILITY
- Headline #E8E8E8 on #0A0A0A = 16.8:1 (AAA)
- Subhead #A0A0A0 on #0A0A0A = 8.4:1 (AAA)
- CTA #0A0A0A on #00E5FF = 12.5:1 (AAA)
- Focus ring visible
- Tap target 48px tall

CONFIDENCE: 90% — assumes dark mode primary; if light mode is the default, swap the bg/fg pair.
FLIP VARIABLE: If the product targets enterprise (conservative typography), reduce display to 40 and weight to 500.

Anti-Patterns

• Random font sizes (no scale)
• Random spacing (no grid)
• 5+ colors
• "Just add a shadow" to fix hierarchy
• Light gray text on white (fails contrast)
• Decoration without function
• Borders when whitespace would do
• Hover styles without focus styles
• No disabled state
• Animation on every element (motion sickness)
• "Make it pop" without saying what should pop and what shouldn't
• Designing for desktop first, mobile as an afterthought