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

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

Or scope it manually:
```css
: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 (`https://unpkg.com/lucide@latest/dist/umd/lucide.min.js`)
- Stroke-based, 24px grid, 1.5px stroke weight by default
- Matches the precise, geometric character of the design system
- Scale to 16px (compact), 20px (default), 24px (prominent)
- Color: inherit from text context — no separate icon colors unless semantic (red for error, etc.)

**Substitution flag:** No custom icon font was provided. Lucide is used as the nearest available match. If Cybersteel has a proprietary icon set, replace Lucide references in `ui_kits/` and update this section.

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

---

## FILE INDEX

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

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
```