// Index

Central Thesis

Logical Brutalism is a design system for high information density contexts, built on the premise that technical truth is a legitimate form of aesthetics in software.

Just as brutalist architecture exposes concrete and refuses decorative coating over real structure, Logical Brutalism exposes system logic: no visual layers that contradict function, no ornament that carries no information, no element that fails to justify its presence with utility.

This is not the absence of design. It is design with maximum justification cost. Every visual decision must answer a functional question before it exists.

"What does not resolve, does not exist."

Critical Distinction

In minimalism, you remove until something looks elegant. In Logical Brutalism, you remove until only what resolves remains. The criterion is functional, not aesthetic.

Application Niche

Logical Brutalism is not a universal system. It is optimised for contexts where maximum information density in minimum screen space is a requirement: IDEs, enterprise dashboards, monitoring tools, internal systems, technical documentation. Where information is the product, Logical Brutalism is the system.

Philosophical Foundation

Three axioms underpin all system decisions. They are premises derived from how humans process information, not from aesthetic preference.

Axiom I :: Function Precedes Form

A visual element exists to convey information or guide action. If it does neither, it is cognitive noise. Norman demonstrated that the brain processes affordances before aesthetics: the user asks what does this do before asking is it beautiful. Beauty is a consequence of well-executed function, never an independent objective.

ref: Norman, The Design of Everyday Things: affordance precedes signifier.

Axiom II :: Exposed Structure

The system does not hide how it works. The logic of hierarchy, state, and behaviour must be immediately readable on the visual surface, with no additional instruction. Kahneman showed that System 1 processes visual patterns before any conscious reading. If the structure is not obvious within 100ms, the design has failed.

ref: Kahneman, Thinking Fast and Slow: System 1 processes pattern before content.

Axiom III :: Restriction as Tool

Fewer options produce more consistency and lower cognitive load. A palette of 6 tokens with strict usage rules is more powerful than 20 colours without criterion. Restriction does not limit design: it defines the system and reduces decision cost for those who implement it.

ref: Alexander, Notes on the Synthesis of Form: form is the resolution of conflicting forces.

Color System

The palette is an attention hierarchy system. Each token maps to a specific urgency level and function. Using a token outside its role breaks system logic.

Tokens

Theme 2 :: Infinity-White (Light)

Canonical parametric inversion for high ambient luminosity. The same mathematical hierarchy inverts signal urgency, ensuring density without glare.

Attention Hierarchy

CSS Reference

:root {
  --color-void: #0A0A0A;
  --color-amber: #FFB000; /* P3 phosphor, 1970s */
  --color-surface: #1E1E1E;
  --color-text: #888888;
  --color-white: #F0F0F0;
  --color-error: #FF4444;
}

[data-theme="infinity-white"] {
  --color-void: #E3E3E3;
  --color-amber: #B35900;
  --color-surface: #CCCCCC;
  --color-text: #4D4D4D;
  --color-white: #0A0A0A;
  --color-error: #BE123C;
}

Typography & Spacing

Two families. Distinct functional roles. Scale in rem based on 16px to respect user browser font size preferences.

Inter :: Human Layer

Designed for reading on high-density screens. Metrics optimised for legibility at small sizes. Use for all content the user needs to read, not scan.

JetBrains Mono :: Logic Layer

Designed for code parsing: monospaced spacing, logical ligatures, maximum clarity in short strings. Use where content is raw system data: labels, status, identifiers, values, timestamps, code.

Typographic Scale

Spacing & Letter Tokens

Complete CSS Reference

:root {
  --font-struct: 'Inter', sans-serif;
  --font-code: 'JetBrains Mono', monospace;
  --radius: 0px;
  --line-height: 1.6;
  --text-display: 2.5rem;
  --text-title: 1.375rem;
  --text-body: 1rem;
  --text-small: 0.875rem;
  --text-label: 0.75rem;
  --text-code: 0.875rem;
  --space-1: 0.25rem; --space-2: 0.5rem;
  --space-3: 1rem; --space-4: 1.5rem;
  --space-5: 2rem; --space-6: 3rem;
  --letter-spacing-code: 0.08em;
  --letter-spacing-struct: normal;
}
html { font-size: 16px; }

Generative Principles

Generative principles dictate what to do and when. Any new decision can be evaluated against them without consulting the author.

P-01 :: Colour Follows State

Before choosing a colour, identify the element’s functional state. Colour is a consequence of state, never an independent choice.

When: New visual element.
How: 1. Define the state: active, inactive, neutral, error, critical. 2. Consult the attention hierarchy table. 3. Apply the token.

P-02 :: Angle as Commitment

90-degree edges declare that the system does not soften reality. Permitted exception: circular progress indicators, where the form carries distinct functional meaning.

When: Every container or bordered element.
How: border-radius: 0 via --radius. Exceptions require documented functional rationale.

P-03 :: Mono for Machine, Sans for Human

JetBrains Mono is the system’s voice: auto-generated data, identifiers, timestamps, status, code. Inter is the content’s voice: text written to be read. The distinction is semantic, not aesthetic.

When: Every typographic element.
How: System-generated data: JetBrains Mono. User-facing content: Inter.

P-04 :: Amber Once Per Screen

The amber accent is the sole element competing with the dark background for maximum attention. If multiple elements are amber simultaneously, the signal loses strength and hierarchy collapses.

When: When using --color-amber.
How: Check if another amber element is active on the same screen. If so, one of them has the wrong role.

P-05 :: Space is Silence

Spacing communicates structure: nearby elements belong to the same context, distant elements belong to distinct contexts. Use spacing tokens to communicate logical relationship, not to fill empty space.

When: Positioning any two elements.
How: Same context: --space-1 to --space-3. Distinct contexts: --space-4 to --space-6.

P-06 :: Immediate and Honest Feedback

Every user action requires immediate visual response via state change. There are no smooth transitions: only discrete states. Dishonest feedback — such as indicating success before server confirmation — is a system integrity failure.

When: Every interactive element.
How: Define all states: default, hover, active, focus, disabled, loading, error. No state without visual response.

P-07 :: ASCII Before Icon

Icons introduce external dependency and require aria-label for accessibility. ASCII is pure text: zero overhead, universal rendering. Use icons only when the symbol is universally recognisable and ASCII cannot represent it with equivalent clarity.

When: When considering adding an icon.
How: Try ASCII first. If using an icon, always include functional aria-label.

Components

Component 01 :: Button

The button is where the user executes. Absence of transition is not negligence: it declares that the system executes without hesitation. Feedback via state change, not via animation.

.btn {
  font-family: var(--font-code);
  font-size: var(--text-label);
  letter-spacing: var(--letter-spacing-code);
  text-transform: uppercase;
  border-radius: var(--radius);
  padding: var(--space-2) var(--space-4);
  min-height: 44px;
  min-width: 44px;
  cursor: pointer;
  transition: none;
}

Component 02 :: Error State

Error is the system's moment of maximum honesty. Four mandatory layers derived from Norman: what failed, why it failed, where it failed, what to do.

.error-container {
  border-left: 3px solid var(--color-error);
  background: var(--color-surface);
  padding: var(--space-3) var(--space-4);
  border-radius: var(--radius);
}
/* ARIA: role=alert ensures automatic reading by screen readers */

Component 03 :: Data Card

The card declares that a data block belongs to the same logical context. The coloured left border is the sole state indicator: a single, unambiguous signal, following Norman.

.card {
  background: var(--color-surface);
  border: 1px solid #2A2A2A;
  border-radius: var(--radius);
  padding: var(--space-3) var(--space-4);
}
.card.active { border-left: 3px solid var(--color-amber); }
.card.error { border-left: 3px solid var(--color-error); }
.card.inactive { opacity: 0.5; pointer-events: none; }

Component 04 :: Loader

Loading is the only context where motion is permitted. Rationale: system activity feedback is functional, not decorative. The ASCII loader preserves aesthetics without introducing library dependency.

/* ASCII Loader — no external dependency */
.loader-ascii::after {
  content: attr(data-frame); /* JS alternates: | / - \ */
  font-family: var(--font-code);
  font-size: var(--text-label);
  color: var(--color-amber);
  animation: none; /* swapped via JS, not CSS */
}

/* Linear loader — justified border-radius exception */
.loader-bar {
  height: 2px;
  background: var(--color-surface);
  position: relative;
  overflow: hidden;
}
.loader-bar::after {
  content: '';
  position: absolute;
  height: 100%;
  width: 40%;
  background: var(--color-amber);
  animation: lb-slide 1.2s linear infinite;
}
@keyframes lb-slide { from { left: -40%; } to { left: 100%; } }

ASCII Symbols :: Reference

When using ASCII as an action, the element must have explicit role and aria-label.

Accessibility

Accessibility is not a concession. It is consistency with Axiom I: function precedes form. An interface unreadable by some users has failed in function before form.

Contrast :: WCAG 2.1

Accessibility Checklist

Contrast and Size

• [ ] Body text: minimum 1rem (16px) — never below
• [ ] System labels: minimum 0.75rem (12px) — never for body reading
• [ ] All colour pairs pass WCAG AA (column above)

Interaction

• [ ] All interactive elements have min-height and min-width of 44px
• [ ] focus-visible defined for all interactive elements
• [ ] Tab order follows reading logic (tested with Tab)
• [ ] No interactive element depends exclusively on hover

ARIA and Semantics

• [ ] Errors use role=alert for automatic reading by screen readers
• [ ] Functional icons have aria-label with functional description
• [ ] Decorative elements have aria-hidden=true
• [ ] ASCII symbols used as action have role and aria-label
• [ ] Information conveyed by colour also present in text

Substitution Test

Remove all colours from the interface. The information hierarchy must still be readable in grayscale. If not, the layout depends on colour to communicate structure: this is an architecture failure.

Evaluation Criteria

Any implementer can audit an interface against this checklist without consulting the author. Any 'no' is a system violation.

Colours

• [ ] Are all colours used within the 6 defined tokens?
• [ ] Does amber (#FFB000) appear on at most one active element per screen?
• [ ] Is red (#FF4444) used exclusively for error states?
• [ ] Are there no gradients present?

Typography

• [ ] Do system data and labels use JetBrains Mono?
• [ ] Does continuous reading text use Inter?
• [ ] Is minimum body text size 1rem (16px)?
• [ ] No third type family added?
• [ ] Does letter-spacing use --letter-spacing-* tokens?

Function

• [ ] Does every visual element answer: what does this communicate?
• [ ] Does no element exist solely for aesthetic reasons?
• [ ] Does the most important component on screen have the amber accent?
• [ ] Do error states follow the four-layer anatomy?
• [ ] Does the loader use ASCII or linear bar?

Accessibility

• [ ] Does body text contrast pass WCAG AA?
• [ ] Do headers pass WCAG AAA?
• [ ] Do all interactive elements have focus-visible?
• [ ] Do touch targets have min 44px?
• [ ] Do functional icons and ASCII have aria-label?
• [ ] Is colour information also in text?

Structure

• [ ] No border-radius beyond documented exceptions?
• [ ] Does spacing use --space-1 to --space-6 tokens?
• [ ] Are all component states defined?
• [ ] Were component Do's and Don'ts respected?

Unresolved Tensions

Every real system contains internal contradictions. Documenting these tensions is not weakness — it is structural honesty. Implementers need to know where the system may need adaptation.

[ Tension ] 12px as Label Minimum

0.75rem (12px) for system labels is a compromise between information density and legibility. WCAG does not define an absolute minimum, but 16px is the established practice for body. 12px may be inaccessible for users with low vision even with high contrast. User testing in real contexts will determine if this threshold is acceptable.

note: v1.2: test with real users and revise if necessary.

[ Tension ] Transition: None and Failure Perception

Absence of transition assumes users prefer instant feedback. This may be false for public interfaces: abrupt state change may be interpreted as system failure, not execution. The principle is correct for internal tools; may need revision in interfaces exposed to non-technical users.

note: v1.2: test instant change perception with general public.

[ Tension ] 6 Tokens is Arbitrary

The choice of 6 colour tokens is not derived from mathematical principle. It could be 5 (remove --color-white and use --color-text for everything) or 7 (add token for charts). 6 is the result of balancing attention hierarchy with minimum restriction. Extensions for specific contexts, such as dashboards with charts, may require additional tokens without violating axioms.

note: v1.2: define palette extension protocol.

[ Tension ] Amber as Canonical Choice

#FFB000 is historically justified by P3 phosphor terminals, but it remains a choice within the 'single saturated accent' restriction. Any saturated colour with sufficient contrast over #0A0A0A would work. Amber is our documented decision, not an absolute system truth.

note: Implementers may substitute with another saturated colour as long as they maintain minimum WCAG AAA contrast over --color-void.

Market Positioning

Logical Brutalism does not exist in a vacuum. Here is where it positions itself relative to existing systems and why someone would choose it over another.

Comparison With Existing Systems

When to Choose Logical Brutalism

When Not To Use

A system that does not admit its limitations is dogma, not architecture.

[ Avoid ] Mass Consumer Products

Interfaces for the general public, children, or the elderly require visual affordances that the system deliberately avoids. Use a system with greater colour, rounding, and familiar icon support.

[ Avoid ] Branding and Marketing

Brand materials need emotional and chromatic flexibility that the system does not offer by design.

[ Avoid ] Visualisations With More Than 6 Colours

Charts requiring extended palettes to differentiate series are incompatible with the 6 tokens. Palette extension for this context is outside the scope of v1.1.

[ Avoid ] When the Context Demands Otherwise

Dogmatism is not part of the philosophy. If the user, the business, or the context requires another approach, use another system.

References

Manifesto

Changelog

Semantic Versioning

The system follows semver: MAJOR.MINOR.PATCH. MAJOR: changes that violate axioms or break compatibility. MINOR: new components, tokens, or principles without violating axioms. PATCH: bug fixes, text clarity, CSS adjustments.

Permitted Extensions

Extensions are additions to the system that do not violate the axioms. Every extension must: 1. Name the axiom that grounds the addition. 2. Define when to use and when not to use. 3. Include its own evaluation checklist. Extensions that violate an axiom constitute a derived system, not an extension.

v1.2.0 :: THE ARCHITECTURE UPDATE (2026)

• - [ADD] Official Mobile Optimization (Radical Responsiveness).
• - [MOD] Core migration: PDF-first to Living HTML Documentation (Axiom II).
• - [MOD] Repository Structural Overhaul: Decoupling core distribution from showcase demos.
• - [ADD] Internationalization: Full English UI with multi-language documentation bridge (EN, PT, ES, DE, ZH).
• - [ADD] Python-based CLI Scaffolder (lb-init.py) for backend integration.

v1.1.0 :: 2026

• + Amber accent #FFB000 replacing green #00FF00 — P3 phosphor reference
• + Unresolved Tensions section added
• + Market Positioning section added
• + Manifesto rewritten — operational version without anthropomorphism
• + Do's and Don'ts added to all three components
• + Loader component added with ASCII and linear bar
• + ASCII symbol table with ARIA added
• + Tokens --letter-spacing-code and --letter-spacing-struct added
• + Redundancies removed — single accent mentioned once per section
• + Central thesis corrected: 'a legitimate form' instead of 'the only legitimate form'

v1.0.0 :: 2026

• + Initial system version
• + 6 colour tokens with attention hierarchy
• + Typography in rem based on 16px
• + Spacing system with 6 tokens
• + 7 generative principles with WHEN and HOW
• + 3 components: button, error, card
• + Accessibility section with WCAG checklist
• + References: Le Corbusier, Rams, Alexander, Norman, Kahneman, Krug, Victor