---
name: vshaders-design-guidelines
description: "Design, build, or extend a vshaders surface: the registry site, effect detail pages, package documentation, or launch material. vshaders is an independent registry of composable WGSL effects built on vgpu. Its visual system is a technical HUD (FUI): strict black and white, square corners, hairline frames, small dense type in Inter and JetBrains Mono, a 120rem full-width container, and 12-column grids that treat whitespace the way a studio page does."
---

# Design vshaders surfaces

Act as a design engineer building a developer tool in the vgpu ecosystem. vshaders is a registry: people and coding agents come to find an effect, see it running, understand what it imports, and copy it into their project. Every design decision serves that job.

This document is modeled on Vercel's public design guidance (vercel.com/design.md) and shares its judgment: precise, calm, technically literate, evidence-led, restrained. It diverges where the material demands it, and each divergence is stated below.

## Attribution

vshaders is an independent, open-source project built on [vgpu](https://vgpu.sh), and this document is modeled on Vercel's public design guidance with attribution. That's the whole stance: credit the sources, then build with confidence. vshaders has its own identity (its wordmark, its live-shader hero); Vercel's brand assets (wordmark, triangle, the `vbg-*` foundation) stay theirs. The goal is a surface that feels at home next to a Vercel property while being unmistakably vshaders.

## Priority order

When requirements compete, protect them in this order:

1. The effects themselves: live, honest, performant. Never a video, never a screenshot posing as live rendering. If WebGPU is unavailable, say so plainly and name what can render the page.
2. The evidence of composability: an effect's import manifest is content, not chrome. It appears with the effect, verbatim, matching the shader source.
3. Monochrome restraint in everything around the canvases.
4. A composition specific to the material; no generic landing-page template.

## Visual system

### The one rule that governs color

**Chrome is monochrome; the canvases carry the color.** Every pixel of saturated color on a vshaders page comes from a shader rendering live. UI color is limited to the link/action blue and, when states exist, the standard semantic colors. This is the vshaders reading of Vercel's "design in monochrome, color only with meaning": here the shader canvas *is* the meaning, and the quieter the chrome, the louder the work.

Corollary: Vercel's hard reject of decorative gradients applies to chrome only. A gradient inside an effect canvas is the product. A CSS gradient on a heading, button, or background is banned. The only non-canvas gradient allowed is a black scrim over a canvas for text legibility.

### Tokens

The palette is strictly black and white: links are ink distinguished by underline, not by a hue. The registry defaults to dark: it is a dark room, and the shader canvases are the light source. The light column exists for future surfaces that need it (long-form docs, print); a surface commits to one scheme, and there is never a visible theme switcher.

| Token | Light | Dark | Role |
|---|---|---|---|
| `--bg` | `#ffffff` | `#080809` | Page canvas |
| `--fg` | `#171717` | `#ffffff` | Primary text |
| `--muted` | `#666666` | `#999999` | Secondary text |
| `--border` | `#eaeaea` | `#262626` | Hairlines, canvas frames |
| `--surface` | `#fafafa` | `#0a0a0a` | Code and manifest blocks |
| `--link` | `#171717` | `#ffffff` | Alias of the ink; links read by underline |

Do not invent additional color tokens. A new need is a design question, not a token addition.

### Typography

Inter for everything readable: prose, headings, labels, values. JetBrains Mono for code, file names, package specifiers, effect ids, commands, and the `label` variant; never for whole sentences. Load both through `next/font/google` at module scope (CSS variables `--sans` and `--mono`).

**All copy renders through the `Text` component** (`components/text.tsx`): `<Text as="h3" variant="heading">`. Never write a loose `<p>`, `<h*>`, or `<span>` with text and ad-hoc styles. The variants are the type system: `display`, `title`, `heading`, `lede`, `body`, `muted`, `label` (UPPERCASE mono, 11px, 0.12em tracking: eyebrows, group titles, small wayfinding), and `mono` (identifiers as written, 11px). This mono-caps grammar is shared with emalorenzo.com (its `type-ui`/`type-caption` tokens), as is the header: wordmark left, nav centered, meta right, inactive links at 42% ink. If no variant fits, that is a design question: add a variant to `Text` and `globals.css`, don't inline a style. The long-form article contracts (`.doc`, `.prose`) are the one exception: their content pages render plain elements and the contract styles them.

- The scale is small and dense, instrument-panel not billboard: display tops out near 2.75rem, titles near 1.75rem, body at 0.875rem. Headings are weight 600, sentence case, tracking tightens with size.
- Body is weight 400, line-height 1.6, measure near 60 to 68 characters.
- Uppercase belongs to exactly one place: the `label` variant (JetBrains Mono, 0.75rem, `0.08em` tracking, muted). An effect id like `effect 001 · mesh-gradient.wgsl` is the `mono` variant, lowercase as written; it is an identifier, not a decoration.
- No em dashes in copy. Use periods, colons, or commas.

### Layout and surfaces

The container runs edge to edge up to `--container-max: 120rem`, with a `--gutter: 2rem` horizontal padding (dropping to 1rem below the 1280px xl breakpoint). Every section composes on a 12-column grid (`--grid-gap: 2rem`): children claim explicit column spans, and empty columns are placed whitespace, not leftover margin. Asymmetry is encouraged where the material supports it (code left, argument right; specimens alternating sides; prose starting at column four), and the grids stack below 1100px.

The page is one continuous canvas and every corner is square: border-radius is 0 everywhere, no exceptions. Earn every border: a canvas viewport gets a hairline frame because it is a real boundary between page and live rendering; a manifest block gets a `--surface` background because it is code. HUD corner brackets (two 14px L-marks in `--muted`) may frame a major surface like the hero. Nothing else gets a box by default. No cards inside cards, no shadows, no glass.

Shader canvases keep a black background in both themes, like a code block keeps its own scheme. Hero text sits on canvas, so it is fixed white over a black scrim regardless of theme.

Specimens follow one grammar: canvas, then id, title, one-paragraph blurb, import manifest. Equivalent items share exact roles and alignment. The import manifest must match the shader source line for line; when one changes, change the other.

### Motion

Stillness in the chrome; all motion lives inside the canvases, where it is the product. No scroll reveals, parallax, marquees, or hover theatrics. Under `prefers-reduced-motion`, every canvas renders exactly one frame and stops; the page must be complete as a still image.

### Copy

Sentence case everywhere. Plain verbs, no hype: the work is the proof, so describe what an effect does and what it imports, and stop. Name things by what the reader controls (an effect, a package, a uniform), not by internals. Define a term once in plain words, then use it consistently.

## Reject list

Inherited from Vercel's guidance and enforced here:

- All-caps outside the `label` Text variant, and decorative section numbering.
- Em dashes.
- Decorative gradients, glows, textures, grid backgrounds, or glass in chrome.
- Centered generic hero copy over a stock background; the vshaders hero is a live effect or it is nothing.
- Badge and pill capsules for ordinary metadata.
- Icon tiles, decorative icons, stock imagery, fake screenshots.
- Scroll-triggered reveals and decorative motion.
- A visible theme switcher, or mixing both token columns on one surface.
- Vercel's own brand assets (wordmark, triangle logo, `vbg-*` foundation); vshaders has its own identity.

## Accessibility floor

Semantic landmarks, one `h1`, ordered headings, visible focus (2px `--link` outline), canvases carry `role="img"` with a meaningful label, WCAG AA contrast in both themes, keyboard-complete interactions, and honest fallback text when WebGPU is missing. Reduced motion is respected as specified above.

## For agents

This file is served at `/design.md`, in the spirit of vercel.com/design.md. When building or modifying any vshaders surface: read this file first, use the tokens table verbatim, set every piece of copy through the `Text` component with an existing variant (add a new variant only when none fits, never a one-off style), and run the reject list over your output before finishing. The repository's `AGENTS.md` covers engineering conventions; this file owns visual and copy decisions.