Valyrian Steel

Forged for clarity. Tempered for the open web.

Overview

Creative North Star: “Valyrian Steel”

Valyrian Steel is a deliberately quiet personal design system. It should feel precise, durable, editorial, and unmistakably made by one person. Its strength comes from a narrow range of materials used with discipline: a cold OKLCH value ramp, one restrained interaction accent, Geist typography, a fixed centered rail, fine rules, and motion that stays beneath the surface until it has a job.

The naming vocabulary is intentionally narrow. Valyrian Steel names the system and its nine-step neutral palette; Targaryen Ember names the primary accent. Typography, layout, components, motion, sound, accessibility, and machine interfaces use direct technical names. Never extend the theme into sigils, medieval ornament, fantasy typefaces, textures, or fan-site imagery.

The site is static-first Astro with progressive enhancement. Its HTML must remain complete when scripts, animation, sound, embeds, maps, Mermaid, clipboard access, or local storage are unavailable. Every enhanced layer should make the experience more tactile without becoming a dependency.

Key Characteristics:

• A centered, site-wide reading rail shared by header, main content, and footer.
• Value carries emphasis before weight, color, borders, or effects.
• Geist carries almost everything; Newsreader Italic is one literary interruption; JetBrains Mono is reserved for operational text.
• Desktop narrative can be deliberately justified, while mobile reading returns to start alignment.
• Persistent navigation changes physical position by viewport: top on desktop, bottom on mobile.
• Motion, sound, theme, presence, and navigation use synchronized state and lifecycle rules.
• Human pages, Markdown, structured data, feeds, and read-only agent tools describe the same public truth.

The Valyrian Steel principle. Add nothing because the page feels empty. Strengthen hierarchy, rhythm, evidence, or interaction until the existing material carries the page.

Restraint principle. A detail earns permanence only when it improves understanding, continuity, accessibility, or the feeling of direct manipulation.

Colors

The palette is one nine-step Valyrian Steel scale at OKLCH hue 240. Light mode begins in Winter Snow and writes with Dragonglass. Dark mode begins in Dragonglass and writes with Winter Snow. The same ramp supplies muted text, rules, glass borders, shadows, code surfaces, scrollbars, and disabled states.

Valyrian Steel scale

Semantic accents and state

• Targaryen Ember is the vermilion interaction signal. It marks reading progress, active anchors, presence, selection, and rare semantic focus. It is never general decoration.
• Warning is amber for tips, warnings, and warm semantic states.
• Information is blue for informational state.
• Important is violet for important state.
• Caution is red for caution and destructive state.
• Success is green for success and constructive state.

Each semantic color has light and dark values in the normative frontmatter. Pair color with copy, iconography, position, or shape so meaning never depends on color alone.

Theme parity principle. Light and dark are equal expressions of the same hierarchy. Do not invert a page mechanically and accept weaker contrast, heavier chrome, or changed emphasis.

Accent scarcity principle. Targaryen Ember should remain scarce enough that its appearance always means something.

Contrast principle. Body copy uses the highest practical contrast. Muted values are for hierarchy, never for hiding essential text.

Typography

Primary font: Geist Variable. Geist carries prose, headings, navigation, controls, labels, tables, dates, and values. The metric-matched Geist Fallback reduces layout shift while the local variable font loads.

Literary font: Newsreader Variable Italic. Newsreader is reserved for the site’s single serif moment: quotations and similarly authored literary interruptions. It is not an alternate heading system.

Operational font: JetBrains Mono 400. JetBrains Mono is reserved for code, commands, paths, hashes, timestamps, keyboard hints, raw tokens, and short identifiers. It is never used as a costume for technical seriousness.

Fluid scale

The official DESIGN.md typography schema cannot represent clamp(), so the frontmatter records the real families, weights, leading, tracking, and features. This table is the normative fluid-size extension.

Weight hierarchy

• Geist 400 carries body copy, quotations, and most labels.
• Geist 450 changes navigation emphasis without creating a width jump.
• Geist 500 marks controls, compact labels, and deliberate utility emphasis.
• Geist 550 carries section headings and durable hierarchy.
• Geist 600 is rare, used for major prose headings and strong semantic emphasis.

Leading, tracking, and features

• Tight leading is 1.3, snug is 1.4, normal is 1.68, and relaxed is 1.72.
• Body copy uses ss01, cv11, optical sizing, no synthetic faces, antialiasing, and optimized legibility.
• Large headings may track between -0.012em and -0.022em. Never go tighter than -0.04em.
• Tabular numerals stabilize clocks, counts, and aligned values.
• Heading text balances; body text wraps prettily; critical identifiers may break anywhere rather than overflow.

JetBrains Mono optical alignment

JetBrains Mono sits optically high beside Geist, icons, or other inline elements. Mixed inline contexts receive a 1px downward optical adjustment. This includes timestamps, hashes, paths, endpoint labels, keyboard hints, footer time, and compact metadata. Standalone code blocks, multiline code, all-mono fields, Mermaid source, and syntax-highlighted regions remain unshifted.

Reading measure principle. Reading text stays close to 60 to 68 characters per line. The site uses a 54ch hero measure and a 42rem prose measure rather than stretching to fill large screens.

Value hierarchy principle. In the homepage introduction, value carries emphasis. Primary statements use the foreground; asides use muted steel. Weight remains regular.

Monospace principle. Use JetBrains Mono only for content that benefits from fixed-width rhythm or operational recognition, then apply the 1px optical correction when it shares a baseline with another typeface or icon.

Layout

The site-wide structure is one centered content rail that holds the sticky header, main content, and center-viewed footer. It is fixed enough to create a recognizable silhouette and fluid enough to breathe between 640 and 720px.

Content rail geometry

• Rail maximum: clamp(640px, 46vw, 720px).
• Rail gutter: 20px on each side.
• Hero measure: 54ch.
• Prose measure: 42rem.
• Header zone: 6.5rem.
• Main top spacing: 64px.
• Standard content lead after a page label: 2.25rem.
• Standard section turn: 4.5rem.
• Standard rule separation: 4.25rem.
• Standard footer separation: 96px.
• Homepage rule, section, and footer rhythm: 2.75rem.
• Spacing steps: 4, 8, 12, 16, 24, 32, 48, 64, and 96px.
• Minimum interactive target: 44px.

The body is a flex column with a minimum height of 100dvh. Main content grows so the footer resolves at the bottom without becoming a detached full-width band. Grid and flex children use zero minimum inline size so long code, URLs, tables, diagrams, and formulas scroll locally rather than widening the document.

Desktop composition

The circular monogram stays at the top of the content rail. It and the segmented Home, Work, More navigation share one glass vocabulary but retain different silhouettes. The homepage narrative is fully justified above 38rem. Justification is an authored editorial treatment, not a global prose default.

Mobile bottom navigation

At 38rem and below, the desktop navigation disappears and the navigation moves to the bottom edge. Its frame remains 14rem wide, centered, safe-area aware, and stable across routes. All three words remain visible. Only the active destination reveals its icon. The active expansion reflows siblings inside a fixed frame, so the bar never resizes or jumps between pages.

Mobile top chrome retains the monogram, palette action, and theme action. The bottom bar is at least 3.25rem high, each tab has a 44px target, and the body reserves 5.5rem so fixed navigation never covers the footer. Justified narrative returns to start alignment with pretty wrapping and no hyphenation.

Alignment principle. Header, content, and footer share the same horizontal edges. A wider surface must prove that the reader needs the width.

Overflow principle. Never conceal document overflow. Reflow first, then introduce a local scroller for evidence that genuinely needs width.

Fixed chrome principle. Fixed chrome must reserve content space, respect safe areas, and remain reachable with zoom, keyboard, and coarse pointers.

Elevation & Depth

The system is flat until interaction. Hierarchy comes first from type, value, spacing, fine rules, and density. Shadows are structural responses for floating chrome, overlays, selected navigation, tooltips, toasts, and elevated interactive previews.

Shadow vocabulary

• Low elevation: a 6px vertical offset and 18px soft blur at 12% mixed foreground. Used for active pills and low elevation.
• Floating surface: an 8px vertical offset and 30px blur at 22%. Used for toasts and meaningful floating surfaces.
• Overlay elevation: a 20px vertical offset and 60px blur at 22%. Reserved for overlays.
• Inset highlight: a one-pixel inset highlight drawn from Winter Snow. Used inside translucent chrome.

The circular header controls use a theme-aware translucent surface, one fine border, an inset highlight, and backdrop blur because they must remain readable over scrolling content. Reduced transparency replaces the material with the solid canvas and a stronger rule.

Elevation principle. A static reading surface does not need a shadow. Elevation appears only when spatial separation or interactive state requires it.

Boundary principle. Prefer either a border or a shadow. Use both only when the border defines glass or an overlay edge that the shadow alone cannot communicate.

Shapes

The system combines precise small radii with two earned silhouettes: the circle and the pill. The monogram, theme control, and compact header actions are circles because their content is centered and singular. Navigation and compact segmented controls are pills because selection moves laterally inside them.

The radius scale is 2, 4, 6, 7, 8, 10, 16, and 999px. The 6px step belongs to quiet footer controls, and the 8px step belongs to compact tooltips. Reading surfaces, diagrams, code figures, and overlays use 10 or 16px. Inline code and compact labels use 4px. Focus uses the smallest 2px radius so the ring follows the element without becoming a second shape language.

Hairline rules are always one pixel. Form follows function: tables remain rectilinear, prose is not boxed, callouts use subtle containment, and cards do not become a default page scaffold.

Shape principle. Circles hold singular chrome actions. Pills hold compact choices. Ordinary metadata gets neither.

Hairline principle. Fine lines may divide, underline, or draw attention, but never become decorative rails or heavy borders.

Components

Persistent header

The persistent header carries the monogram, desktop navigation, and mobile actions. It survives ClientRouter navigation, then recomputes active state from the live URL. The logo lifts by one pixel on hover, compresses to 0.95 on press, and can reveal the build date after a deliberate pointer hold. Touch long-press remains owned by the operating system.

Segmented desktop navigation

Desktop Home, Work, More navigation uses a sliding foreground pill. Inactive items remain quiet until hover or focus. Active weight is pre-reserved so changing from 400 to 450 does not reflow siblings. Pill position, width, and height move together with the shared spring.

Mobile bottom navigation

The mobile navigation is a fixed, stable frame. Words are permanent; the active icon expands from zero width. It can retreat during intentional scrolling but must return for navigation and keyboard interaction. It is hidden in print.

Command palette

The command palette opens globally with / or Command/Ctrl-K. Desktop discovery remains keyboard-led rather than adding another search icon. Mobile receives an explicit compact trigger where keyboard discovery is not dependable. The palette searches local content, Pagefind, curated utilities, recents, pins, AI files, and nested actions without live APIs, tracking, or background dependencies.

The palette traps interaction rather than focus by accident: it locks document scroll, restores the exact prior scroll and focus, keeps its own list as the scroll container, preserves nested state against late async results, and supports Arrow keys, Home, End, Enter, Escape, and action mode.

Centered footer

The footer is the centered closing plane of the content rail. It combines source revision, presence, AI and standards links, Colophon, sound, and theme without becoming a separate content section. The clock can cycle between Ashwin’s time, visitor time, and time difference. Its width stays stable with tabular numerals. On mobile, source detail compresses and the footer wraps without colliding with the bottom navigation.

Presence indicator

The presence dot is time-derived, not surveillance. Its state is computed locally from Ashwin’s timezone. Awake, winding-down, and asleep states change pace and color, with accessible copy in the clock tooltip. Reduced motion removes pulse and breathing while preserving the state.

Location map

The MapLibre location card uses keyless OpenFreeMap tiles, grayscale treatment, a locally meaningful pin, and a static fallback. It loads only when useful, removes its map on page cleanup, and never becomes a tracking dependency.

Quote surface

The quote surface is the one serif moment. Newsreader Italic, hanging punctuation, right-aligned attribution, restrained controls, and flip continuity make it feel authored without introducing a second general-purpose type system.

Toast notifications

Toasts confirm copied text, state changes, failures, and small discoveries. They use inverse canvas and foreground, a 10px radius, anchored or corner placement, local stacking, and a short rise. They never contain essential content without an equivalent persistent state.

Markdown reading system

Long-form Markdown uses build-time math, dual-theme syntax highlighting, lazy Mermaid, callouts, anchors, code copy, tables, footnotes, TOC, scroll-spy, reading progress, and external-link treatment. Source remains readable when JavaScript fails. Code and wide evidence scroll locally.

Sound library

The sound library is a tiny dependency-free Web Audio engine, off by default and gated behind a real user gesture. The cue vocabulary is:

The engine uses a master gain of 0.09. Its current score is executable documentation:

Sound never carries unique meaning. Preference is local, survives navigation, and synchronizes across tabs. Unsupported Web Audio, storage failure, muted hardware, and first-load autoplay restrictions are harmless.

Motion system

Motion uses two curves and five durations:

• 90ms: press feedback.
• 150ms: color and quiet state.
• 200ms: movement and page arrival.
• 420ms: larger physical changes.
• 640ms: authored entrances.
• Standard easing: cubic-bezier(0.2, 0, 0, 1) for controlled movement.
• Spring easing: cubic-bezier(0.34, 1.56, 0.64, 1) for short tactile settling.

The old page remains still during navigation while the new page fades in over 200ms. Global section entrances use a 640ms spring with a 70ms capped stagger. The homepage narrative owns a 620ms five-line cascade at 40, 100, 155, 205, and 250ms. Body content is visible by default and never depends on an observer to be read.

Focused motion principle. One interaction owns the focal motion at a time. Parent and child entrances must not compound.

Continuity principle. Persisted chrome, active navigation, theme, sound, and page lifecycle must agree after every ClientRouter transition.

Do’s and Don’ts

Do

• Do preserve the centered content rail, 20px gutter, center-viewed footer, and stable page silhouette.
• Do keep designated desktop narrative fully justified and switch it to start alignment below 38rem.
• Do use value, spacing, and typography before adding color, weight, surfaces, or motion.
• Do apply the JetBrains Mono 1px optical correction in mixed inline contexts.
• Do keep Home, Work, More in the persistent navigation and keep desktop command-palette discovery keyboard-led.
• Do reserve at least 44px for touch targets and provide visible focus for every interactive control.
• Do keep content complete without JavaScript, sound, maps, embeds, local storage, clipboard access, or animation.
• Do preserve exact protocol boundaries and label experimental, legacy, discovery-only, optional, and unavailable capabilities honestly.
• Do use semantic HTML, one H1, ordered headings, direct labels, local scrollers, and text alternatives.
• Do update identity facts, JSON-LD, AI context, summaries, and machine surfaces together.

Don’t

• Don’t extend Game of Thrones naming beyond Valyrian Steel, its nine neutral palette aliases, and Targaryen Ember.
• Don’t rename stable CSS variables, component APIs, routes, font families, or protocol identifiers to match those public aliases.
• Don’t add a desktop search icon, extra main-navigation destinations, or a disconnected CTA section.
• Don’t stretch prose across wide screens, globally justify technical content, or preserve desktop composition by shrinking mobile text.
• Don’t use gradients, glows, ornamental shadows, card grids, decorative icons, oversized pills, or color without meaning.
• Don’t gate reading behind motion, autoplay sound, or require hover for essential information.
• Don’t use JetBrains Mono for ordinary prose or apply its 1px shift inside standalone code.
• Don’t claim standards maturity, live verification, authentication, payment, or write capabilities that the deployed system does not have.
• Don’t add live APIs, analytics, visitor tracking, a backend database, or paid runtime dependencies.
• Don’t use em dashes in copy, documentation, or source comments.

Experience and Machine Contract

Accessibility and preference media

The system targets WCAG 2.2 AA. It uses landmarks, a skip link, ordered headings, visible focus, named controls, local status announcements, 44px touch targets, non-color state cues, and high-contrast reading text. Reduced motion removes displacement, stagger, pulse, and progress animation. Reduced transparency removes backdrop blur. Increased contrast strengthens distinction. Forced-colors mode preserves native visibility. Print resolves to the light palette and removes interactive chrome.

Progressive enhancement and performance

The initial document is static HTML. Client scripts add theme persistence, navigation continuity, the command palette, sound, map, Mermaid, clipboard, scroll-spy, reading progress, presence, and small interaction details. Every initializer is idempotent and re-enters on astro:page-load. Page listeners use a shared AbortSignal; observers, timers, and maps register cleanup before swaps.

Fonts are local and metric-matched. The map and Spotify embed load lazily with stable placeholders and useful fallbacks. Mermaid imports only when a diagram exists. No feature may create a layout jump merely because it loads late.

Content and Markdown

The Markdown pipeline runs diagrams and math before highlighting, then callouts, heading anchors, code figures, tables, and external links after highlighting. This order is architectural. Mermaid and math bypass Shiki; code figures see highlighted pre elements; the heading metadata adopts the IDs created by the anchor plugin.

Notes expose raw source. Core pages have Markdown mirrors. HTML pages negotiate Markdown through Accept: text/markdown, vary on Accept, identify a canonical HTML page, and expose an approximate token count. Feeds carry full note content. Pagefind indexes the human pages without creating a live search service.

Search, SEO, AEO, and GEO

• SEO: trailing-slash canonicals, sitemap XML, robots policy, Pagefind, Open Graph, Twitter cards, descriptive metadata, local fonts, stable rendering, and page-specific schema.
• AEO: factual summaries, FAQPage answers, concise headings, excerpts, direct definitions, stable identity facts, and answer-ready structured data.
• GEO: the llms.txt family, ai.txt, knowledge.json, AI summary JSON, Markdown aliases, full-text feeds, entity consistency, attribution guidance, and explicit freshness boundaries.
• Structured data: Person, WebSite, ProfilePage, BlogPosting, BreadcrumbList, CollectionPage, SoftwareApplication, Book, CreativeWork, and FAQPage are emitted only where truthful.

Agent interfaces

The site provides multiple read-only routes to the same public truth:

• MCP Streamable HTTP at /mcp, with tools, resources, prompts, a catalog, and status metadata. The implementation advertises protocol version 2025-06-18 and does not claim a later version.
• A deterministic read-only A2A endpoint and Agent Card.
• Browser registration through the experimental WebMCP draft. document.modelContext is the primary draft interface; navigator.modelContext is compatibility behavior.
• Agent Skills Discovery v0.2.0, an API catalog shaped by RFC 9727, DNS-AID publication notes, security.txt, and optional RFC 9421 response signatures.
• OAuth, OpenID Connect, Auth.md, commerce protocols, claim, revoke, payment, and registration metadata are discovery-only or unavailable exactly as their public documents state.

No agent surface creates sessions, modifies content, issues credentials, reads private accounts, accepts mandates, or moves money.

Agent Readiness Contract v1.0

The phrase Complete against Agent Readiness Contract v1.0 may be used only when all required criteria have current evidence:

Capability provenance is one of: RFC or formal standard, official protocol, draft or experimental, community convention, site-defined, or legacy compatibility.

Capability status is one of: Verified live, Verified build, Browser-enhanced, Optional deployment, Discovery-only, Unavailable by design, or Provisional.

Unavailable capabilities count as readiness successes only when the absence is intentional, published, and tested. A build result must never be presented as live evidence. The deployed commit shown by the page is the evidence boundary for live claims.

Privacy, security, and trust

Local-first visitor tools make no background request unless the user opens a feature that requires public data. Recents, pins, theme, and sound preference remain in browser storage. Presence is calculated from time and timezone, not measured from Ashwin’s activity. The site has no account, database, private agent context, or visitor profile.

Security headers, content signals, crawler policy, permission policy, protocol cards, and security.txt are public and testable. Optional response signing remains absent when no signing key is configured. Discovery metadata must not be mistaken for operational authentication or commerce.

Governance

This file is the normative human and machine design contract. The CSS is the executable implementation. They change atomically and a drift test prevents silent divergence. The approved palette aliases remain descriptive and never replace technical identifiers outside the design contract.

The HTML design page displays its actual build timestamp and commit. This Markdown records contract version 1.0 and the last audited date, while avoiding a self-referential commit hash. Identity changes follow the repository-wide identity checklist. Design changes update this file, the internal sidecar, relevant Colophon copy, and the verification fixtures together.

Contract version: 1.0

Last audited: 2026-08-09

Current verification state: Verified build; live state must be established after deployment.