cybersteel/README.md

Cybersteel Design System

Overview

Cybersteel is a retrofuturist design system built in direct opposition to modern "fluffy, bloated, web slop" software. It channels the excitement and optimism of early computing — the era when a computer felt like a portal to the future, not a distraction machine.

The system is grounded in three technical principles:

• Rock-solid reliability — nothing crashes, flickers, or stutters
• High performance — things load instantly, no layout shifts, no spinner theatre
• Radical directness — do not waste the user's time; get the job done and get out of the way

The visual language is a direct expression of these values. It is not decoration for its own sake — every visual choice maps to a technical or philosophical intent.

Retrofuturist inspirations:

• Art Deco (1920s–40s): geometric precision, gold ornament, symmetry, angular forms
• Gruvbox color theme: warm dark backgrounds, muted earth tones, vivid accent colors
• Fallout game series: amber CRT glow, terminal aesthetics, atomic-age optimism

Sources provided: None (this design system was created from description only). No Figma links, codebases, or existing assets were supplied.

---

CONTENT FUNDAMENTALS

Voice & Tone

• Direct, imperative, technical. Address the user as a capable adult. No hand-holding.
• Second person ("you"), present tense. "Your build failed." Not "It looks like there may have been an issue with your build."
• No filler words, no exclamation points, no emoji. Cybersteel copy never says "Great job!" or "Looks like something went wrong 😬"
• Sparse. Every word must earn its place. Delete the adjectives. Delete "currently." Delete "simply."
• Confident. No hedging ("might," "perhaps," "it seems"). State facts.
• Technical vocabulary is welcomed, not dumbed down. Users are professionals.

Casing

• UI labels: Title Case for navigation, Sentence case for body, ALL CAPS for status indicators and section headers
• Headings: Title Case preferred at H1/H2, sentence case for H3+
• Buttons: ALL CAPS or Title Case, never mixed

Examples of Good Cybersteel Copy

• BUILD COMPLETE — 1.4s ✓ vs. Your build finished successfully! ✗
• No results. ✓ vs. Hmm, we couldn't find anything matching that query 🔍 ✗
• Access denied. ✓ vs. Oops! It looks like you don't have permission to view this. ✗
• 47 errors. Fix them. ✓ vs. There are some issues we need to address together 😅 ✗

What Cybersteel Never Says

• "Oops", "Whoops", "Uh oh", "Hmm"
• "We're working on it", "Bear with us"
• "Looks like...", "It seems like..."
• "Please don't hesitate to..."
• Emoji of any kind in product UI

---

VISUAL FOUNDATIONS

Color

Based on the Gruvbox palette — warm, dark, earthy. Not cool blue-grey like modern dark modes. The warmth evokes old paper, amber screens, and aged metal.

• Backgrounds: Very dark warm browns/blacks. Not pure #000000 — always warm.
• Foreground: Warm cream/ivory, never pure white
• Accent — Gold: The signature color. Art Deco gold, amber terminal glow. Used sparingly: borders, highlights, interactive states.
• Accent — Red: Danger, errors, critical alerts
• Accent — Green: Success, safe, complete
• Accent — Blue/Teal: Info, links, cool technical elements
• Accent — Orange: Warnings, in-progress, hot paths
• All accent colors have a dim (bg-facing) and bright (fg-facing) variant

See styles.css for all tokens.

Typography

Primary brand typeface: IBM Plex Sans. Used for display, body, and condensed roles by default. Self-hosted from /fonts (woff2). Weights available: 300, 400, 500, 600, 700 (plus 300/400/500 italic). SIL OFL — free for commercial and embedded use.

Primary monospace: IBM Plex Mono. Used for --font-mono — code, terminal output, data values, timestamps, and any tabular or log-like content where character alignment matters. Same designer, same skeletal proportions, so it sits cleanly next to Plex Sans on the same screen. Same weights, same license, same self-hosting.

Three semantic roles:

• Display (--font-display): Titles, hero text, section headers. → Plex Sans, 600–700 weight, ALL CAPS with wide tracking at H1/H2.
• Body (--font-body, also --font-condensed): UI text, labels, descriptions, prose. → Plex Sans, 400–500.
• Mono (--font-mono): Code, terminal output, data values, timestamps. → Plex Mono.

Mono mode (opt-in)

For surfaces where the terminal aesthetic IS the point — consoles, status dashboards, IDE-like internal tools, hardware-grade hero moments — flip the whole surface into Plex Mono with the .mono-mode class. Display, body, and condensed all resolve to Plex Mono; structural CSS is unchanged.

<body class="mono-mode"> … </body>

Or scope it manually:

:root { --font-display: var(--font-mono); --font-body: var(--font-mono); --font-condensed: var(--font-mono); }

Do not introduce Orbitron, Barlow, Share Tech Mono, or any other family. If something looks like it needs a different typeface, the answer is weight, size, tracking, casing — or a deliberate switch to Mono mode for the whole surface.

Type scale is based on a 1.25 modular ratio. Minimum body size: 14px (web), 12pt (print).

Spacing

8px base grid. All spacing tokens are multiples of 4px, with the main scale in multiples of 8px.

Backgrounds

• Default: dark warm bg, no images
• Feature sections: translucent gradient overlays (warm amber/gold tints at low opacity, ~5–12%)
• Cards: slightly lighter bg than page, with a 1px warm border
• NO full-bleed photography unless explicitly specified
• Subtle geometric Art Deco texture possible via CSS (repeating-linear-gradient patterns)
• Scan line overlays at very low opacity (~3–5%) acceptable for terminal-style elements

Gradients

• Simple, translucent, warm-toned
• Direction: top-to-bottom or diagonal (135deg)
• Used as overlays, not solid fills
• Colors: gold/amber → transparent, or bg-dark → bg-darker
• Never rainbow, never cool-toned, never noisy

Borders

• 1px solid is the standard — always visible, always crisp
• Color: --border (warm mid-grey) for structural, --gold-dim for decorative/Art Deco accents
• Hairline Art Deco ornament: thin double-line borders (border-bottom: 1px + offset) for headings
• Corner radius: 0–4px max. Sharp corners preferred. Cybersteel does not round its corners like a toy.

Cards

• background: --bg-active (one step lighter than page)
• border: 1px solid --border
• border-radius: 2px
• Subtle inner shadow on hover: inset 0 0 0 1px --gold-dim
• No drop shadows — flat, structural, mechanical

Animation & Motion

• Fast and purposeful. No decorative animations.
• Transitions: 150ms ease-out (UI state changes), 80ms linear (cursor/immediate)
• No bounce, no spring, no elastic
• No enter/exit animations on simple UI elements
• Allowed: fade-in on modals/overlays (200ms ease), scanline flicker on terminal elements
• Hover: color shift only — no scale, no float, no glow explosion

Hover & Press States

• Hover: text/icon brightens (fg2 → fg1 → fg0 progression), border lightens
• Press/Active: slight background darken (bg1 → bg0), border becomes gold
• Focus: 1px gold outline, 2px offset — crisp, not blurry
• No box-shadow: 0 0 20px gold glow effects

Iconography

• Geometric, minimal, monochromatic
• Stroke-based (not filled)
• Lucide Icons (CDN) as primary icon set — closest to the aesthetic
• No emoji in UI; unicode geometric characters (▶ ■ ◆ ▲) acceptable as decorative elements
• See ICONOGRAPHY section below

Imagery

• Minimal imagery in UI
• When used: high contrast, desaturated or warm-toned, grain optional
• No stock photo cheerfulness
• Amber/sepia toning preferred

Transparency & Blur

• backdrop-filter: blur() used sparingly — overlays/modals only
• Translucent surfaces: background: rgba(var(--bg-surface-rgb), 0.85)
• Never used purely decoratively

Layout

• Fixed sidebar widths (e.g. 240px, 280px)
• 8-column or 12-column grid for content areas
• Generous whitespace within dense information — breathe between groups, not within them
• Fixed header/nav is acceptable; sticky sidebars acceptable
• No carousels, no infinite scroll decorativeness

---

ICONOGRAPHY

Primary set: Lucide Icons

• Source font: fonts/lucide/lucide.ttf
• Icon-name/codepoint map: fonts/lucide/codepoints.json
• The current font workflow uses the Lucide TTF as its only source; it does not use SVGs
• Lucide provides one regular face with its upstream 2px icon geometry
• Scale to 16px (compact), 20px (default), 24px (prominent)
• Color: inherit from text context — no separate icon colors unless semantic (red for error, etc.)

Export status: The pinned Lucide TTF and codepoint map are present. The application-specific subset exporter is not implemented yet.

Supplementary unicode glyphs (Art Deco ornament):

• ◆ ◇ — diamond separator
• ▸ ▾ — directional indicators
• ■ □ — toggle/status squares
• ═ ║ ╔ ╗ ╚ ╝ — box-drawing for terminal chrome
• · — interpunct as list separator

Never use emoji in product UI.

ICON FONT EXPORT

The pinned Lucide font inputs are under ./fonts/lucide/. This directory intentionally contains only:

• lucide.ttf — the canonical base font.
• codepoints.json — the Lucide icon-name to private-use codepoint map.

The TTF is the correct source format for the exporter: it works in native applications and can produce TTF, WOFF, WOFF2, and other delivery outputs. WOFF2 is a delivery format, not the archival or transformation source.

Lucide ships one regular font face. Its font weight does not control icon stroke width. The current workflow does not generate weight variants; subsetting the premade font preserves Lucide's regular 2px appearance.

Create a subset directly

pyftsubset removes unselected glyphs from the Lucide TTF. Pass the selected Unicode codepoints with --unicodes.

Example using three Lucide glyphs:

mkdir -p build

pyftsubset ./fonts/lucide/lucide.ttf \
  --unicodes=U+E0F5,U+E151,U+E193 \
  --output-file=build/cybersteel-icons.ttf \
  --layout-features="*"

Generate WOFF2 from the same source and selection:

pyftsubset ./fonts/lucide/lucide.ttf \
  --unicodes=U+E0F5,U+E151,U+E193 \
  --output-file=build/cybersteel-icons.woff2 \
  --flavor=woff2 \
  --layout-features="*"

Generate WOFF instead with --flavor=woff and a .woff output path. Keep the original Lucide private-use codepoints. pyftsubset retains the required .notdef glyph and removes unselected icon glyphs.

The current Lucide font is one regular face. Subsetting removes unused icons but does not change stroke width or create light/bold variants. Do not request synthetic bold for the icon font.

For web delivery, emit one @font-face declaration and CSS classes only for selected icons. Keep Lucide codepoints stable unless there is a specific reason to remap them. Keep the ISC license and the MIT notice for Feather-derived icons with redistributed output.

Official sources: Lucide static assets, Lucide icon font guide, Lucide license, and release 1.31.0.

---

FILE INDEX

README.md                        ← This file
SKILL.md                         ← Agent skill definition
styles.css              ← All CSS custom properties (colors, type, spacing, effects)

fonts/lucide/
  lucide.ttf            ← Canonical Lucide font source
  codepoints.json       ← Icon-name to codepoint map

assets/
  texture-scanline.svg           ← Scanline texture overlay

preview/
  colors-base.html               ← Base background/foreground palette
  colors-accents.html            ← Accent color swatches
  colors-semantic.html          ← Semantic color roles
  type-display.html              ← Display typeface specimen (Plex Sans)
  type-body.html                 ← Body type scale (Plex Sans)
  type-mono.html                 ← Monospace / terminal specimen (Plex Mono)
  type-sans.html                 ← Sans vs. Mono mode comparison
  spacing-tokens.html            ← Spacing scale
  borders-radius.html            ← Border styles and radius tokens
  shadows-elevation.html         ← Shadow system
  components-buttons.html        ← Button variants and states
  components-inputs.html         ← Form input states
  components-cards.html          ← Card components
  components-badges.html         ← Badges and status indicators
  components-nav.html            ← Navigation patterns

ui_kits/
  app/
    README.md                    ← UI kit notes and component list
    index.html                   ← Interactive app prototype
    Layout.jsx                   ← Shell: sidebar + topbar + content area
    Terminal.jsx                 ← Terminal/console component
    DataTable.jsx                ← Dense data table
    StatusBar.jsx                ← Bottom status bar
    CommandPalette.jsx           ← Keyboard-driven command palette