dotfiles/home_root/.claude/skills/australis-design/README.md

# Australis Design System

> Cool, calm, terminal-first. A dark color and UI system inspired by the Aurora Australis — the Southern Lights.

Australis is a **comfort-focused dark theme** for technology products. The color core was already defined (16 ANSI-style terminal colors, all cooler than neutral, medium-contrast, perceived LAB lightness 65 base / 80 bright). This system extends that core into a full visual language: typography, spacing, elevation, motion, and component patterns suited to terminals, code editors, dashboards, and developer tooling.

The original color spec lives in `uploads/README.md` — © 2024 Vuong Hoang.

---

## Index

- **`README.md`** — this file (visual + content foundations, iconography)
- **`colors_and_type.css`** — design tokens (CSS custom properties + base element styles). Import this from any HTML.
- **`SKILL.md`** — front-matter for using this as a downloadable Claude Skill
- **`assets/`** — logo (mark + wordmark) — see _Caveats_ below
- **`preview/`** — design-system preview cards (registered for the Design System tab)
- **`ui_kits/terminal/`** — interactive terminal + code-editor surface (the signature use-case)
  - `index.html`, `Terminal.jsx`, `Editor.jsx`, `StatusBar.jsx`, `Sidebar.jsx`, `CommandPalette.jsx`

## Sources we were given

- **`uploads/README.md`** — the Australis Dark color theme spec (full palette + rationale)
- _No codebase, Figma, or product screens were supplied._ The "technology stack" framing in the brief is interpreted as **developer tooling** (terminal, editor, CLI dashboard) — that's the surface this system is built for. If a real product exists, send it over and we'll re-skin the UI kit accordingly.

---

## Content Fundamentals

Australis copy reads like good terminal output: **direct, lowercase-leaning, low ceremony**. Information dense, never chatty.

- **Tone** — calm, technical, slightly understated. Confident without exclamation marks. Think `man` page meets a well-lit cabin.
- **Voice** — second-person (`you`) for instructional copy. First-person plural (`we`) only when the system is doing something on behalf of the user (`we'll never share it`). Avoid "I" — there's no persona.
- **Casing** — sentence case for everything: buttons, headings, menu items. The wordmark itself is lowercase: `australis`. Eyebrows and metadata may be UPPERCASE (mono, wide-tracked) — that's the only place caps appear.
- **Punctuation** — periods optional on UI strings of one short sentence. Use em-dashes for asides. Code identifiers, hex codes, and paths go in `monospace`.
- **Numbers + units** — keep tight: `184ms`, `12kb`, `v1.2.0`. Spell out only when prose-natural ("twelve modules").
- **No emoji.** No exclamation marks. No marketing superlatives. Status uses glyphs (`✓ ✗ !`) or icons, not emoji.
- **Vibe** — engineer-grade clarity. The product respects the user's attention.

**Examples**

> ✓ tokens compiled (184ms)
> ! 2 deprecated tokens — see migration.md
> ✗ assets/logo.svg not found

> Use 8+ characters with mixed case.

> Aurora prod · staging · preview

> Deploy · Cancel · Learn more

---

## Visual Foundations

### Palette philosophy

- Three families: **Ice** (surface neutrals, cool-tinted), **Aurora** (primary blue/cyan/green — use generously, in that preference order), **Dawn** (red/yellow/magenta accents — use sparingly).
- Neutral scale shifts from cool blue toward green as it brightens. This is the signature — don't flatten it.
- Black = `#222531`, never pure `#000`. White = `#a9bcc3`, never pure `#fff`. The eye sits in low-contrast cool grey; emphasis is achieved by *brightness*, not saturation.
- Semantic mapping: info → blue, success → green, warning → yellow, danger → red. Magenta is reserved for keywords / brand moments.

### Backgrounds

- **Always dark first.** No light mode in this system.
- Solid fills only on chrome — no full-bleed photography, no decorative gradients.
- One sanctioned gradient: the **aurora glow**, a vertical `bright-blue → bright-cyan → green` (see `--glow-*` tokens, the logo, and accent edges). Used at low opacity, never as a background fill behind text.
- No textures, no noise, no patterns. The screen is the polar sky — empty, with light *coming through* it.

### Type

- **Display** — Space Grotesk (geometric humanist; -0.015em tracking).
- **UI / Body** — Inter (15px default body, 1.5–1.65 line-height).
- **Mono** — JetBrains Mono (terminal, code, eyebrows, metadata, hex codes).
- Eyebrows and metadata are **mono uppercase, 11px, 0.08em tracked** — this is one of the system's signatures. Use them often.
- Min sizes: 11px on UI metadata; 13px on body in compact density; 15px default. Never below 11px.

### Spacing & layout

- 4px base. Use the `--sp-*` scale; don't invent in-between values.
- Information density is **medium-high**, especially in chrome (toolbars, sidebars). Marketing surfaces breathe more.
- Containers: `sm 640 / md 880 / lg 1200 / xl 1440`. Center on canvas; no full-bleed marketing layouts.

### Borders

- Default border `--border-default` (`#565f69`) at 1px. Subtle dividers use `--border-subtle` (`#414751`).
- **Border > shadow** for grouping in chrome. Cards layer one subtle shadow on top of a 1px border.
- Featured cards use a 2px **top edge** in `--aus-blue` instead of changing the fill — this is the only sanctioned "accent border" pattern. Never colored *left* borders (the LLM-slop trope).

### Corners

- `--radius-sm` (4px) for inputs, badges, small chrome.
- `--radius-md` (6px) for buttons, tags.
- `--radius-lg` (10px) for cards, panels.
- `--radius-pill` only for status badges and toggle switches.
- Terminal/editor surfaces stay at `--radius-md` or `--radius-lg`. The inner code area itself is square.

### Shadows / elevation

- Shadows are tinted with `rgba(10, 12, 18, *)` — cooler than pure black, matching the bg.
- 4 elevation steps. Most chrome lives at `shadow-1` or `shadow-2`. Modals at `shadow-3`. Heavy popovers at `shadow-4`.
- **Aurora glow** (`--glow-blue/cyan/green`): used as a 3px focus ring or a hover lift on primary buttons. This is the system's signature interaction motif.
- **Inset shadow** (`--shadow-inset`) for terminal wells and sunken inputs — subtle highlight on top edge + dark inner border.

### States

- **Hover** — shift one step *brighter* on neutrals (e.g. `bright-black → dark-30`). Primary buttons: `blue → bright-blue`. Never lower opacity to indicate hover.
- **Active / pressed** — slight downward shift (`translateY(1px)`) + a step *darker* on neutrals, or a desaturated primary.
- **Focus-visible** — 3px aurora glow ring (`--glow-blue` by default; `--glow-green` for success controls).
- **Disabled** — `opacity` is fine here; combine with `cursor: not-allowed`.

### Motion

- Calm, never bouncy. No springs, no overshoot.
- `--ease-out` for entries, `--ease-in-out` for state changes, `--ease-aurora` for hero/long transitions.
- Durations: `120ms` for hovers, `200ms` for state, `320ms` for panels, `800ms` for hero.
- Aurora glow may breathe on the brand mark (8s slow opacity oscillation) — this is the only continuous animation sanctioned by default.

### Transparency & blur

- Glass surfaces (modals, popovers over content) use `--bg-glass` (`rgba(55,59,70,0.55)`) with `backdrop-filter: blur(16px)`. Cap at 16px blur — anything more turns muddy on cool palettes.
- Scrims use `--bg-overlay` (`rgba(34,37,49,0.72)`) — solid feel, no blur.
- Otherwise, opacity is for disabled states only.

### Imagery

- Black-and-white or cool-tinted photography. No warm-tinted hero imagery — it fights the system.
- Reserved use; this is a chrome-first system, not an editorial one.

### Layout fixtures

- Top chrome: 44–52px tall (status bar / tab bar).
- Sidebar: 240–280px (collapsible to 56px icon rail).
- Status bar: 24–28px (mono, 11px).
- Hit targets: 32px min in dense chrome, 40px+ in marketing/settings.

---

## Iconography

Australis uses **[Lucide](https://lucide.dev)** — a clean, line-first icon set that matches the system's pen-stroke restraint.

- **Stroke weight** — `1.75` (slightly heavier than Lucide default for legibility on dark).
- **Default size** — `22px` in chrome, `16px` in dense lists.
- **Color** — `currentColor`. Always inherit from the surrounding text (use `--fg-1` or `--fg-2`).
- **Style** — line, never filled. Two-tone is forbidden.
- **No emoji** anywhere in the UI. Status uses Lucide icons (`check-circle`, `x-circle`, `alert-triangle`, `info`) or mono glyphs (`✓ ✗ ! ➜`).
- **Unicode glyphs** — sanctioned for terminal/CLI surfaces only: `➜ ✓ ✗ ! ⚡ ●`. They feel native there. Outside the terminal, use Lucide.

### Where to get them

The CDN is the simplest path: `<script src="https://unpkg.com/lucide@latest"></script>` and `lucide.createIcons()`. For static HTML cards (preview surfaces), inline the SVG with `stroke-width="1.75" stroke="currentColor" fill="none"`. The `preview/brand-icons.html` card shows 16 hand-inlined examples in the right shape.

If you need a glyph Lucide doesn't have, draw it with the same constraints: 24×24 viewBox, 1.75 stroke, rounded caps + joins, no fill.

---

## Caveats

- **Logo** — no real logo was provided. The `assets/logo-mark.svg` and `assets/logo-wordmark.svg` are interpretive placeholders (an aurora curtain over a horizon) sized to the system. **Replace with the real mark** when available, or tell us the brand voice and we'll commission one.
- **Type stack** — Space Grotesk / Inter / JetBrains Mono is **canonical**. Loaded from Google Fonts at the top of `colors_and_type.css`; exposed via `--font-display`, `--font-sans`, `--font-mono`; documented in _Visual Foundations → Type_.
- **Product surface** — no codebase or screens were attached. The UI kit (`ui_kits/terminal/`) reflects the *kind* of product Australis is built for (a developer tool); it's not a recreation of an existing product.