j3w1 UI Theme Spec

Identity

What the j3w1 theme is, where it came from, and the five rules that keep a port recognisable.

True-black canvas (#000000), near-black panels (#100c0c) and chrome (#090707), with dark-red raised layers, rose interface text (#e99499), near-white reading text (#f4eeee), dark-red selections (#531310), a bright red focus ring (#e53935), 1px square borders, zero radii, one monospace family for chrome, reading and code. Red marks interaction: focus, selection, active borders, primary actions. It is not a decoration and it is not applied to everything. Darkness is the canvas; readable content is the priority.

Five rules keep an implementation recognisable:

1. Preserve the warm-black / rose / red identity. Never substitute a charcoal-and-blue dark theme because the target ships one.
2. Use the role assigned to a token, never the token whose colour happens to look closest.
3. Keep content, selection, keyboard focus, diagnostics and changed text distinguishable from one another. Selection is a fill; focus is a ring.
4. Nothing is rounded, blurred, glowing or gradient-filled. Elevation is a 1px border and, for modals, a backdrop.
5. Preserve the host application’s behaviour, keyboard handling and accessibility settings. Geometry and typography limits of a host are documented deviations, not reasons to rewrite it.

Where it came from

The palette began as a Manjaro i3 workstation preserved in j3w1/1w3j: a pywal ramp pulled from a red wallpaper, then frozen and hand-tuned slot by slot in config/Xresources while watching what ls, vim and the agnoster prompt actually rendered. The i3 configuration supplied the rest of the idiom: 1px pixel borders, 14/−2 gaps, tabbed layouts, a hidden top bar with Chinese status labels, dunst toasts framed in #ae1914, dmenu selections in #630f0d.

The contemporary reference is j3w1/j3w1.github.io, a working web reinterpretation of that workstation. Its stylesheet named the roles this specification adopts (--terminal, --surface-raised, --selection, --focus, --prose, --muted …) and wrote the first contrast contract. Both sources are pinned by revision in references/sources.json; after adoption this repository is the authority and later changes in either source are proposals, not automatic updates.

What “modern” means here

Clear organisation, responsive behaviour, strong keyboard and screen-reader support, precisely specified states, and controls that are pleasant to operate. It does not mean pill buttons, glass panels, gradients, neon glows, a Material-style redesign, or red on every surface. Sixteen concrete misreadings are rendered as labelled non-examples on the site.

The specification page’s generated literal-color previews have the narrow geometry, checkerboard and motion exception recorded in D-014; the component and consumer rules remain as written.

Profiles

• default — the approved everyday composition. Monochrome red/rose for chrome, text, borders, interaction and actions; three bounded hues (amber, green, blue) for status, diagnostics and diffs (D-001); monochrome syntax.
• heritage-ansi — the sixteen Xresources slots and the historical assignments, exact, including the ones that fail the contrast floor. For terminals, archives and fidelity; never for new interface text.
• extended — a proposed overlay that colours syntax, a full sixteen-slot semantic terminal palette and chart series with the same three hues. Not approved; the site labels it.

Naming

Roles are color.<group>.<role> with a closed group list: surface, text, border, interaction, action, status, code, diagnostic, diff, terminal, chart, icon. Primitives are color.primitive.<family>.<step> where the step rises with luminance. A CSS custom property is the path with dots replaced by dashes: color.interaction.focus.ring → --color-interaction-focus-ring. Roles alias primitives; primitives carry provenance.

Foundations

Surfaces, text ladder, borders, interaction states, focus, typography, spacing, density, elevation, motion, icons and layout, with the rules that govern each role.

Values live in tokens/; this document says what each role means and where it may be used. Every rule below is normative for the default profile.

Surfaces

surface.desktop and surface.canvas use true black (#000000). Readable content sits on the canvas or default (#100c0c) panels and cards, raised (#160b0b) for sticky headers, menus and popovers, overlay for dialogs and drawers, sunken (#000000) for reading and detail panes, input for form-control fills, chrome and chrome-alt for window frames and bars. Layering is subtle by design; it may not erase the boundary of a control, which is why controls also carry border.control.

Never tint photographs, video, document content or user-defined data colours to put more red on screen.

Text ladder

Ordinary text must reach 4.5:1 against its actual background in every state. #a3676b and #7d1310 are never text roles in default, even when a particular darker background improves their ratio; they remain in service as border.control, icon.decorative, status.neutral.fill and border.disabled. Metadata and comments that a person needs to read are not decorative and use text.subtle, not a graphic colour.

The specification page’s generated literal-color previews have the narrow geometry, checkerboard and motion exception recorded in D-014; the component and consumer rules remain as written.

Borders

Every border is 1px (border.width.default); 2px (border.width.emphasis) is reserved for the selected indicator bar, the sticky-header rule and the invalid border. The quote rule is the one wider edge, at twice the emphasis width, because it marks a block rather than bounding a control. border.divider (#2b0e0d) separates rows and sections; border.default (#531310) is decorative and may never be the only visible edge of a control; border.control (#a3676b, 4.71:1) is the boundary of every form control at rest; border.active (#e53935) marks the focused or active control; border.overlay (#e53935) frames every floating layer. Styles: solid by default; dashed only for focus, drop targets and read-only fields; dotted for hints; double for conflicts. Radius is 0 everywhere, including checkboxes, switches, chips, avatars, badges and tooltips.

Interaction states

Every interactive component declares which of these apply and demonstrates every applicable one, including the combinations. Precedence when several apply: disabled > loading > invalid > selected > pressed > hover; focus-visible is always drawn on top and never suppressed by another state.

Rules that apply everywhere:

1. Selection is a fill; focus is a ring. Neither borrows the other’s form. A ring still has to be visible on whatever it sits over: #e53935 measures 2.52:1 on action.primary.bg and 1.13:1 on status.danger.fill, which is why the ring recolours on those fills instead of relying on hue. It measures 3.38:1 on the interaction.selection.bg recessed by D-027, so a selected row keeps the ordinary control ring.
2. Focus ring (D-006; component mapping clarification D-015). Controls and rows: outline: 1px dashed {color.interaction.focus.ring}; outline-offset: -2px. Focusable containers (panes, windows, dialogs, cards): outline: 2px solid {color.interaction.focus.ring-container}; outline-offset: -3px. On filled surfaces use the component’s explicit ring mapping: primary buttons and checked controls use interaction.focus.ring-container where declared; destructive buttons use their declared on-fill text role. The selection fill is the exception and takes the ordinary ring, on the measurement in rule 1. Keep the control or container geometry independently of the colour mapping. :focus:not(:focus-visible) draws nothing. Forced-colors mode uses Highlight. A host focus indicator is never removed without this replacement.
3. Never colour-only. Every state and every status carries a second channel: a glyph (✕ ! ✓ i ·), a border width, an underline pattern, or an ARIA state. Charts carry pattern fills.
4. Hover changes fills and borders, never text colour alone, and only on hover-capable pointers.
5. Disabled never uses opacity. Opacity leaks the background and breaks contrast accounting.
6. Contrast floor. Text ≥ 4.5:1 and control boundaries, rings and meaningful graphics ≥ 3:1 against the actual background of the state, measured after compositing translucent colours.
7. Motion. Durations are 80 / 120 / 150 ms at most, on opacity, transform and background only; under prefers-reduced-motion: reduce every duration is 0.01 ms, nothing slides or shimmers, and no behaviour waits on transitionend.

Actions

Four button tones. primary is the only filled button at rest (action.primary.bg #7d1310 with text.prose, 9.28:1); secondary is an outline (border.control, text text.bright); tertiary is a ghost or icon button (text.default, hover interaction.hover.bg); destructive is an outline in action.destructive.text (#f73f35) that fills with action.destructive.hover-bg (#dc282e) and #f9faf9 text (4.58:1) on hover, and a filled variant for confirm dialogs. Destructive actions also require a confirmation step or an undo affordance; the colour is not the safeguard.

Status, diagnostics and diffs (D-001)

Five statuses: danger (#f73f35 text, #dc282e fill), warning (#c9973f), success (#86a46f), info (#7e9ebb), neutral (#bd787d text, #a3676b fill). Each has text, fill, on-fill, tint and border roles, a mandatory glyph (✕ ! ✓ i ·) and a distinct underline or border pattern (wavy, dashed, solid, dotted, double). The three extension hues are desaturated and warm-shifted so they sit inside the identity, all between 6.5:1 and 7.6:1 on every surface, and are forbidden in surface, text, border, interaction and action. Purple, cyan and magenta do not exist in the theme.

Diagnostics: error = wavy #e53935 underline, #f73f35 text, #e53935 stripe, #2b0e0d line background; warning = wavy amber; info = dotted blue; hint = dotted text.subtle; unused = text.muted with a dotted underline. Diffs: added = #0f1a0e line background, green gutter mark and +, word-level additions as a 2px green underline (no fill, so text contrast is untouched); removed = #2b0e0d background, red gutter mark and −, word-level removals underlined and struck through; modified = #1f1a0c background, amber gutter mark and ~; conflicts = a double #f73f35 border. Textual markers and existing status icons are always preserved.

Code and terminal

Editor surfaces use code.bg (#0c0909), code.current-line (#1c0a09), code.line-number (text.subtle, replacing the site’s #7d1310), caret #e99499, selection #420f0c (muted text stays 4.71:1 inside it), search matches #630f0d with the current match inverted (#ffa2a7 on #0c0909), bracket match as a 1px #e53935 border, indent guides #531310, rendered whitespace #7d1310 (decorative). Syntax in default is monochrome: keywords #f73f35, strings #bd787d, comments #ad7175 italic, numbers and constants #d4868b, functions #ffa2a7, variables and operators #e99499, types #b37175, properties and headings #e53935, tags #f73f35, attributes and escapes #d4868b; invalid text takes a wavy underline, deprecated text a line-through. Languages inherit these roles; a language-specific override needs a documented reason.

Terminal roles carry the sixteen slots exactly in every profile. Slots 1, 4, 6, 8, 9, 10, 12, 13, 14 and 15 do not reach 4.5:1 on the terminal background (slot 15, #a3676b, measures 4.45:1; slot 0 is the background itself); the theme documents this rather than normalising it, because programs, not the theme, choose which slot means what. Inside an editor selection (code.selection-bg, #420f0c) muted text stays at 4.71:1 but the keyword, type, property and comment roles fall below 4.5:1; a selection is a transient state and the limitation is recorded, not hidden. The extended overlay proposes a semantic sixteen-slot palette that all reaches 4.5:1.

Links use strong red text.link (#f73f35) and a persistent underline, distinct from the rose body and heading ladder (D-024). Hover uses near-white text.link-hover on interaction.hover.bg (D-027; the strong fill read louder than the link itself and stays with menu items). Current-page and selected navigation use their explicit indicator and on-fill roles.

Typography

One family: SauceCodePro NFM (Source Code Pro through the Nerd Fonts build), falling back to Source Code Pro, Cascadia Mono, Consolas, Liberation Mono, DejaVu Sans Mono and monospace. The site records size-adjust metrics for the fallbacks; no font file is distributed. Weights 400 and 700 plus italic. Scale (size/line-height in px): ui-sm 12/16, ui-md 13/18, ui-lg 14/20, reading 15/24, code 13/19, terminal 13/19 with −0.5px letter-spacing, h1 20/28 bold, h2 16/24 bold, h3 13/18 bold in text.accent, caption 11/16 only with text.muted or lighter. Hosts keep the user’s chosen size; tiny UI text is a reference-implementation metric, not a rule.

Spacing and density (D-009)

Spacing steps: 0, 1, 2, 4, 8, 12, 16, 24, 32, 48 px. Two density modes applied with data-density on any subtree: compact (control 24px, row 28px, ui-sm type, 8px horizontal padding, 2px gaps) matches the workstation; comfortable (control 32px, row 36px, ui-md type, 12px padding, 4px gaps) suits everyday applications. Both meet the 24×24 CSS-pixel target minimum; compact requires 4px between adjacent targets. Table rows are exempt and always take the comfortable row height: a data row is content rather than chrome, and compacting it costs scannability where it is needed most. Controls inside a row still follow the page density. The site’s 3px i3 gap, 14/−2 window gaps and 28px bar are window-manager geometry, not theme tokens.

Elevation and layering

There are no shadows except shadow.floating (0 6px 22px rgb(0 0 0 / 55%)) on the i3 floating-window specimen. Floating layers are a 1px border.overlay on surface.raised; modals add surface.backdrop (rgb(0 0 0 / 65%)). Stacking: canvas 0 < raised 1 < popover 10 < drawer 20 < dialog 30 < toast 40 < skip link 1000.

A popup opened by hovering follows the pointer: it sits 8px from the cursor, flips to the other side of it rather than crossing a viewport edge, keeps an 8px margin from every edge, and is repositioned on pointer move, scroll and resize. A popup with nothing to operate takes no pointer events, so it cannot stand between the cursor and what opened it; one that carries a control or a link stays reachable and holds while the pointer is inside it. Either closes when the pointer leaves both the trigger and the popup.

The same popup opened from the keyboard anchors to its trigger instead — below it, or above when there is no room below — because focus has no pointer to follow. This is a placement rule only: what opens a popup, and whether it is a tooltip, a preview or an inspector, is the component’s own contract.

Icons

SVG line icons on a 16px grid, 1.5px stroke, stroke: currentColor, fill: none, sizes 12 / 16 / 20. No icon font is required; Nerd Font glyphs appear only in terminal and heritage specimens. Icon-only controls carry aria-label and a tooltip. icon.decorative (#a3676b) is for glyphs that convey nothing on their own.

Layout

Reading measure 72ch, content column 680px, application layout 1440px. Breakpoints 320 (reflow floor), 600, 900, 1280. Components use container queries; sidebars collapse to drawers below 900px; data tables scroll horizontally with a sticky first column below 600px; the page never scrolls horizontally at 320px. Right-to-left mirrors breadcrumb separators, pagination, sidebar and drawer sides, wizard progression, affixes and tree indentation.