---
name: Xpykerz
colors:
  background: '#090b0d'
  surface: '#12161a'
  primary: '#b6f23a'
  text: '#f4f5f3'
  muted: '#8b949e'
  border: '#252b31'
---

# Design System: Xpykerz

## How agents should use this guide

Use this document when extending this site or reproducing its visual identity in another project. Read it before choosing colors, fonts, spacing, or component treatments. Preserve the visual language while adapting the layout to the requested content.

This guide records the current implementation, extracted on 2026-10-24. The source of truth is the homepage (`src/pages/index.astro`), the error page (`src/pages/404.astro`), and the web manifest (`public/site.webmanifest`). When working in this repository, also follow `AGENTS.md`. These are repository paths. Check the source if this document and the implementation diverge.

The site publishes this same document at `/design-guide.md`; the production URL is `https://xpykerz.com/design-guide.md`. The endpoint reads `.stitch/DESIGN.md` during the build, so update this file and rebuild to publish revisions.

Copyable instruction for another agent:

> Read `https://xpykerz.com/design-guide.md` (or `.stitch/DESIGN.md` in the repository) and use the existing Xpykerz theme for this task. Match its palette, monospace typography, spacing, square geometry, thin borders, responsive behavior, and interaction states. Reuse existing patterns. If a required component has no documented precedent, keep the extension minimal and consistent with these primitives.

## 1. Visual Theme & Atmosphere

Xpykerz presents a focused product engineering studio with a restrained terminal aesthetic. A near-black canvas, electric lime accents, and monospace lettering give it a technical character. Large, tightly tracked headlines and a narrow reading column create a clear hierarchy without decorative imagery.

The page is spacious rather than dense: each major section occupies at least one viewport, with content centered vertically and text aligned left. A barely visible engineering grid supplies texture. Depth comes from contrast and hairline borders; the existing design has no shadows, rounded cards, gradients used as color decoration, or photographic hero assets. The gradient functions in the CSS construct the grid and its mask.

Brand wording is short and direct: “Think. Build. Ship.”, “From idea to production.”, and the 404 headline “This page hasn't shipped yet.” Treat these as examples of tone rather than copy to insert into every new component.

## 2. Color Palette & Roles

### Primary Foundation

| CSS token | Value | Name and role |
| --- | --- | --- |
| `--background` | `#090b0d` | Near-black charcoal; page canvas and text on lime-filled actions. |
| `--surface` | `#12161a` | Raised charcoal; site mark and skip-link backgrounds. Use sparingly for contained controls. |
| `--border` | `#252b31` | Dark slate; 1px separators, control outlines, muted underlines, and grid color source. |

### Accent & Interactive

| CSS token | Value | Name and role |
| --- | --- | --- |
| `--primary` | `#b6f23a` | Electric lime; homepage title, eyebrow labels, indices, icons, signature, selected navigation, hover/focus emphasis, and primary action fill. |

Selection on the homepage uses lime background with near-black text. The site mark starts with `color-mix(in srgb, var(--surface) 85%, transparent)` on the homepage, becoming solid surface on hover/focus. The 404 mark uses solid surface throughout.

### Typography & Text Hierarchy

| CSS token | Value | Name and role |
| --- | --- | --- |
| `--text` | `#f4f5f3` | Soft off-white; section headings, feature titles, tagline, and primary reading emphasis. |
| `--muted` | `#8b949e` | Cool gray; descriptions, supporting copy, footer, and inactive navigation ticks. |

### Functional States

The implementation defines one dark theme (`color-scheme: dark`). There are no separate success, warning, error, information, disabled, or light-mode tokens. The 404 page uses the same brand palette. Do not reinterpret lime as a general success color or invent a state palette unless the requested feature needs one.

Preserve these exact six colors when matching the theme. Transparent and alpha versions are compositing treatments, not additional palette colors. Keep browser `theme-color` and manifest theme/background colors at `#090B0D` when reproducing the site shell.

## 3. Typography Rules

### Family & Rendering

All text uses the same system monospace stack:

```css
--font-mono:
  "SFMono-Regular", "Cascadia Code", "Roboto Mono", Consolas,
  "Liberation Mono", monospace;
```

These are local font fallbacks; the site loads no external font files or font service. Actual glyphs vary by platform. Do not substitute a proportional body font or introduce a display font when matching this identity.

The homepage body is `16px`, line-height `1.55`, with `text-rendering: optimizeLegibility`. At widths up to `640px`, body text becomes `14px`. The root font size is not overridden, so `rem` values do not shrink with that body rule; they remain relative to the browser's root font size.

### Hierarchy & Weights

| Element / selector | Font size | Weight | Line-height | Tracking / treatment |
| --- | --- | --- | --- | --- |
| Homepage title `h1` | `clamp(2.75rem, 8vw, 5.8rem)` | Browser heading bold | `0.95` | `-0.07em`; lime; `-0.055em` at ≤640px. |
| Section title `h2` | `clamp(2rem, 5vw, 3.8rem)` | Browser heading bold | `1.03` | `-0.055em`; off-white; max-width `13ch`. |
| Feature title `.feature-copy h3` | `clamp(1rem, 2.5vw, 1.25rem)` | Browser heading bold | Inherited `1.55` | Off-white; margin `0`. |
| `.tagline` | `clamp(0.95rem, 2vw, 1.25rem)` | `600` | Inherited `1.55` | Off-white; margin `0`. |
| `.eyebrow`, `.section-index` | `0.72rem` | `700` | Inherited `1.55` | `0.14em`; uppercase; lime. |
| Main prose / feature descriptions | Body size | Normal | `1.55` | Muted; sentence case. |
| `.hero-description` | `0.84rem` | Normal | `1.55` | Muted; max-width `54ch`. |
| `.signature` | Body size | `700` | `1.55` | Lime. |
| `.feature-number` | `0.72rem` | Normal | `1.55` | Lime. |
| `.scene-dot` | `0.65rem` | Normal | `1.55` | Number hidden with transparent text until active/hover/focus. |
| `.scroll-cue` | `0.7rem` | Normal | `1.55` | `0.08em`; uppercase; muted. |
| Footer | `0.72rem` | Normal | `1.55` | Muted. |
| Site mark | Body size | `800` | Page default | Lime “X”. |

Heading weights are not explicitly declared in the CSS; normal browser heading defaults supply bold. Preserve that result rather than assuming a custom font weight exists in the source.

### Spacing Principles

- Tight negative tracking belongs to large headings. Eyebrows and small utility labels use positive tracking.
- Eyebrows have `1rem` below them. The homepage title has `0.25rem` below it; the hero description has `1.25rem` above it.
- Section headings have bottom margin `clamp(2rem, 5vw, 3.5rem)`. Deliberate line breaks produce compact multiline statements.
- Prose paragraphs have `1rem` below them. The signature has `1.5rem` above it.
- Keep long text readable: studio copy max-width `700px`, feature descriptions `62ch`.

## 4. Component Stylings

### Buttons & Text Actions

The existing filled action appears on the 404 page as `.primary-action`. It is a square rectangle with a `1px` lime border, lime fill, near-black text, padding `0.8rem 1rem`, and `0.78rem` bold monospace lettering. On hover or keyboard focus, its background becomes transparent and its text becomes lime. It has no explicit transition.

The accompanying `.text-action` is muted and underlined, with border-colored decoration and `0.3rem` underline offset. Hover/focus changes its text to lime. Homepage footer links use a `0.25rem` underline offset and the same color change.

There is no existing secondary button, pill button, icon-button library, loading state, or disabled-button treatment. Use the documented action as the starting point when a new action is requested.

### Cards & Feature Rows

Services and projects use flat `.feature-row` elements rather than enclosed cards:

- Grid columns: `2rem 1fr auto`; gap `1rem`; items aligned to the top.
- Top and bottom borders: `1px solid var(--border)`; adjacent rows remove the next top border.
- Padding: `1.5rem 0`; no fill, radius, or shadow.
- Leading number or arrow: lime, `0.72rem`, with `0.2rem` top padding.
- Main copy: vertical flex stack with `0.5rem` gap between heading and description.
- The optional trailing arrow occupies the automatic final column.

Only the linked project row (`.feature-link`) has an interactive treatment. Hover/focus changes its borders to lime and adds `0.75rem` left/right padding over `180ms ease`. Its arrow translates `0.2rem` right and `0.2rem` up over `180ms ease`. Static service rows retain their base styling.

### Navigation & Site Mark

The homepage mark is a fixed “X” in the upper-right corner, inset `1.25rem`, z-index `20`. Its anchor is a `2.4rem` square with a 1px border and centered lime lettering. Hover/focus changes its border to lime and background to solid surface over `160ms ease`.

The homepage section navigator is fixed at right `1.35rem`, vertically centered, z-index `20`. It stacks four links with `0.75rem` gaps. Each link pairs a two-digit number with a 1px horizontal tick. Inactive ticks are muted and `0.55rem` wide. Active/hover/focus ticks become lime and `1.5rem` wide, and their number becomes visible in lime. Tick width and background transition over `180ms ease`.

Links target `#home`, `#about`, `#services`, and `#projects`. An `IntersectionObserver` with thresholds `[0.45, 0.65]` updates `.active` and `aria-current="page"` from visible sections. Visible nav numbers run `01`–`04`; content section labels begin at `01 / Studio` after the hero. Keep the two numbering contexts distinct.

At ≤640px the section navigator is hidden and the mark moves to `1rem` from the top/right. There is no mobile hamburger or drawer in the current design.

### Inputs & Forms

No input, form, dropdown, modal, table, or toast component exists in the current site. This guide does not claim established styles for them. If requested, derive the minimum treatment from the existing monospace font, dark canvas/surface, square edges, 1px borders, and lime interaction emphasis; retain usable labels and visible keyboard focus.

### Grid Texture & Icons

Each homepage scene has a noninteractive `::before` layer covering it. Two linear gradients draw 1px lines using `rgba(37, 43, 49, 0.14)`, on a `48px 48px` grid. A radial mask fades it from black at the center to transparent at `68%`; the layer has opacity `0.22`. Keep both alpha stages: an opaque grid would be much stronger than the source.

The 404 uses a full-body 48px grid with line color `rgba(37, 43, 49, 0.035)` and no radial mask.

Icons are simple inline SVG arrows: no fill, lime stroke, square line caps, stroke width `1.5`. The scroll arrow is `1rem` wide with an `18 × 18` viewBox; the project arrow is `1.35rem` wide with a `24 × 24` viewBox. Decorative SVGs and the blinking cursor use `aria-hidden="true"`. The site mark is text, while existing PNG/ICO assets in `public/` supply browser/app icons.

### Footer

The footer belongs inside the final projects scene. It uses a horizontal flex layout, `space-between`, `1rem` gap, `4rem` top margin, and muted `0.72rem` text. Its link group has `1.25rem` gaps. The year is generated dynamically. At ≤640px both footer and link group become vertical; footer top margin is `2.5rem` and link gap is `0.5rem`.

## 5. Layout Principles

### Grid & Structure

The main content token is `--content-width: 760px`. The homepage consists of four vertically stacked scenes. Each `.scene` is a relative flex container, centered on both axes, with `min-height: 100svh`, `overflow: hidden`, and padding:

```css
padding: 5rem max(1.5rem, calc((100vw - var(--content-width)) / 2));
```

Content wrappers have `width: 100%`, max-width `760px`, and sit above the grid at z-index `1`. The hero overrides width to `auto`, so its compact text block is centered as a unit while its text stays left-aligned. The `content--wide`, `content--compact`, `lockup`, and `scene--projects` classes currently add no separate CSS rules; do not infer extra width variants from their names.

Desktop scrolling uses `scroll-snap-type: y mandatory`; scenes use `scroll-snap-align: start` and `scroll-snap-stop: always`. The document uses smooth scrolling unless reduced motion is requested.

The scroll cue is centered horizontally at the hero's bottom, `2rem` above the edge, z-index `2`, with `0.65rem` between label and icon.

### Whitespace Strategy

There is no formal spacing-token scale in the source. Reuse its recurring values rather than introducing a replacement system:

| Value | Existing use |
| --- | --- |
| `0.25rem` | Homepage title bottom margin; footer underline offset. |
| `0.5rem` | Feature-copy gap; nav number/tick separation; mobile footer-link gap. |
| `0.65rem` | Scroll-cue gap; mobile feature-row gap. |
| `0.75rem` | Scene-nav gap; project-row hover/focus inset. |
| `1rem` | Labels/paragraph margins; feature-grid gap; footer gap. |
| `1.25rem` | Mark inset; hero-description top margin; footer-link gap. |
| `1.35rem` | Mobile scene horizontal padding; desktop nav right inset. |
| `1.5rem` | Feature-row vertical padding; signature top margin; 404 action gap. |
| `2rem` | Scroll-cue bottom inset; minimum section-heading bottom margin. |
| `4rem` | Desktop footer top margin; mobile scene bottom padding. |
| `5rem` | Desktop scene vertical padding. |

### Alignment & Visual Balance

Maintain one dominant text column, left-aligned headings and prose, and generous surrounding space. Lime marks hierarchy and interaction rather than filling large decorative panels. Use separators to organize lists. Keep persistent controls at the edge so the content column remains visually quiet.

### Responsive Behavior & Touch

The CSS starts with desktop rules and overrides them with max-width media queries; font sizes also adapt with `clamp()`.

| Scope / breakpoint | Behavior |
| --- | --- |
| Homepage above `640px` | Full section navigator; mandatory vertical snap; 16px body; desktop scene padding. |
| Homepage ≤`640px` | Proximity snap; 14px body; nav hidden; mark inset `1rem`; scene padding `5.5rem 1.35rem 4rem`; `100svh` minimum retained; feature columns `1.5rem 1fr auto` with `0.65rem` gap; vertical footer. |
| 404 ≤`560px` | Recovery actions stack vertically and align to the start. |

The current mark is `2.4rem` square; the source does not establish a general minimum touch-target token. Do not describe small nav ticks as large touch controls. Verify actual interaction sizes when adding controls.

### Error-Page Variant

The 404 shares the palette, font, square mark, and grid, but is a single centered layout without scene navigation, scroll snapping, cursor, or reveal animation. Its main column is `min(760px, calc(100% - 2.75rem))`, with `min-height: 100svh` and auto horizontal margins.

Its off-white `h1` uses `clamp(2.6rem, 8vw, 5.5rem)`, line-height `0.98`, tracking `-0.065em`, and `2rem` bottom margin. Description width is `62ch` with line-height `1.65`. Recovery navigation sits `2.25rem` below the description with a `1.5rem` gap. The 404 body does not explicitly set the homepage's body line-height or mobile 14px size; retain the distinction when matching that page.

### Motion & Accessibility

- The hero underscore blinks every `1s` with `steps(1)`; opacity becomes zero at the 50% keyframe.
- Under `prefers-reduced-motion: no-preference`, `.reveal` uses a `600ms ease both` view-timeline animation over `entry 18% cover 42%`, beginning `1.5rem` lower at zero opacity. Base content remains visible without the animation rule.
- Under `prefers-reduced-motion: reduce`, smooth scrolling becomes `auto` and the cursor animation is disabled. Existing hover transitions and scroll snapping are not disabled by that rule.
- The homepage skip link targets `#about`, is fixed at `1rem` top/left with z-index `100`, and moves from `translateY(-180%)` to its visible position on focus. It has surface fill, lime text/border, and `0.6rem 0.85rem` padding.
- Keep semantic headings, section `aria-labelledby` attributes, named navigation, labeled mark links, and `aria-current` updates. Match keyboard focus with the documented hover/focus treatments. Existing selectors that remove outlines provide color, border, or padding feedback; preserve visible feedback when extending them.

## 6. Design System Notes for Stitch Generation

### Language to Use

Describe the theme as “a minimal terminal-inspired product engineering studio, with a near-black canvas, electric lime accents, system monospace typography, tightly tracked display headings, fine slate separators, square geometry, and generous whitespace.” Ask for a faint engineering grid and restrained interaction motion.

### Color References

Use near-black charcoal `#090b0d`, raised charcoal `#12161a`, electric lime `#b6f23a`, soft off-white `#f4f5f3`, cool gray `#8b949e`, and dark slate `#252b31`. Preserve their roles from section 2.

### Component Prompts

> Create a Xpykerz hero with a vertically centered, left-aligned monospace lockup in a full-height dark scene. Use a large lime brand title with an underscore cursor, an off-white tagline, a short muted description, a faint 48px engineering grid, and a small outlined X mark in the upper-right corner.

> Create a Xpykerz services section within a 760px text column. Place a lime uppercase index above a tightly tracked off-white heading. Present services as open rows with thin slate rules, small lime numbers, bold monospace titles, and muted descriptions. Keep edges square and spacing generous.

> Create a Xpykerz error page using the same dark palette and monospace font. Center a narrow content column vertically, with a small lime route label, a large off-white headline, muted explanatory copy, a square lime recovery action, and an understated underlined contact link. Stack the actions on narrow screens.

### Incremental Iteration

Match palette and typography first, then content width and whitespace, then borders and states, and finally subtle grid and motion. Avoid introducing rounded cards, shadows, extra accent colors, gradients as decoration, stock photography, or external fonts unless explicitly requested.

For work in this repository, keep page-specific styles/scripts in the existing Astro page pattern. There is no Tailwind setup, component library, shared token module, or external styling dependency to reuse. This document is a specification, not a stylesheet; other projects must implement the values in their own stack.

After implementation, follow repository verification rules: run `npm run build`, inspect `/` and `/404.html` through `npm run preview`, and check desktop/narrow layouts, section links, keyboard focus, reduced-motion behavior, and browser errors. Do not create or modify tests unless the user explicitly requests them.