# Wiggleverse Design System

The core design system for **Wiggleverse.org** — a Washington 501(c)(3)
nonprofit building art and software for a world at peace, on one shared set of
ethics. Its first product is *Ecomm* (Shopify-class commerce at near-zero cost);
the portfolio also names *Apps* and *Learn*, all built on an **Open Core**.

> *Treat humans as humans — everything else follows.*

This system captures the brand exactly as it ships on the marketing site so that
agents and designers can produce on-brand interfaces, decks, and assets.

## Sources

Built from the live marketing-site codebase, the source of truth:

- **Codebase:** `wiggleverse-www/` — static site (plain HTML/CSS/JS, no build
  step), deployed to Cloudflare Pages. Brand tokens live in
  `wiggleverse-www/assets/tokens.css`; the design system CSS is
  `wiggleverse-www/styles.css`.
- **Brand source of truth (referenced, not attached):** `wiggleverse-org/corp` →
  `brand/BRAND.md` (§5–10). The site's `assets/` kit is a vendored copy. The
  site design spec is `corp/docs/superpowers/specs/2026-06-04-wiggleverse-www-design.md`.
- **Fonts** are the real vendored woff2 files (Space Grotesk, Inter, Fraunces),
  copied into `assets/fonts/`. No substitutions were made.

---

## Content fundamentals

How Wiggleverse writes. The voice is **two registers passing through one
review** — the same idea the product is built on.

- **Machine register (default).** Precise, structural, plain-spoken. Most copy
  lives here: headings, UI, body prose. Calm and declarative, never hypey.
  *"We take only what it takes to run."*
- **Human register ("the soul").** Warm, literary, used **sparingly** for the
  lines that carry conscience — taglines and pull-quotes only. Always set in
  **Fraunces italic**. *"We are verbs, not nouns." · "Ethics that cannot be
  checked are just claims."*

Specifics:

- **Person.** Mostly **we / our** (the org speaking plainly and accountably).
  Slips to **first-person singular** for the founder's voice in the About essay
  ("I felt that one firsthand… — Ben Stull, Founder"). Addresses the reader as
  **you** in product/partner copy.
- **Tone.** Honest, humble, anti-extractive, quietly ambitious. Leads with
  *what is enough?* rather than *how much can we get?* Admits limits openly
  ("hand-kept estimates, refreshed monthly for now").
- **Casing.** Sentence case everywhere — headings, buttons, nav. **Eyebrows**
  and small labels are UPPERCASE with wide tracking. Product names are casual
  and lowercase-ish in prose ("ecomm"), Title Case as proper nouns ("Ecomm").
- **Punctuation.** Em dashes for asides. Arrows (`→`) end calls to action
  ("Why Wiggleverse →"). Italic emphasis on the load-bearing question
  (*what is enough?*). Bold for the load-bearing noun phrases in a list.
- **No emoji.** None, anywhere. Status and emphasis come from type and a small
  set of geometric glyphs (see Iconography).
- **Recurring phrases.** "Treat humans as humans." · "We take only what it takes
  to run." · "Radical transparency / we show you the receipts." · "Build the
  dictionary first." · "If you're learning, you're succeeding." · "We are verbs,
  not nouns." · the dedication to Aaron Swartz in every footer.
- **The vibe.** A standards document (RFC/IETF) with a conscience — exact where
  it matters, tender where it counts.

---

## Visual foundations

The whole system answers to one motif: a **Circle of Equals** — one living,
wiggling line through six equal points, closed into a ring, with a **deliberately
empty center** ("no center, no hub, no sun"). The connecting line *is* the ethic.

- **Ground.** **Dark "sky" is primary** (`--wv-midnight #0E1230`). Long-reading
  passages flip to **Paper** (`--wv-paper #F6F4FB`) sections. Most of the system
  lives on dark.
- **Color.** Indigo (`#1C2150`) for raised surfaces; **lilac** (`#9B8CFF`) is the
  accent — links, nodes, "the bonds between us"; **violet** (`#7C6FE0`) is its
  on-paper counterpart; **gold** (`#F4C76B`) is warmth / horizon / the single
  primary CTA color; **starlight** (`#EDEAFF`) is text on dark; **ink**
  (`#3B2F7A`) is text on paper. A near-black **night** (`#090C22`) grounds the
  footer.
- **Type.** Two machine faces + one human face. **Space Grotesk** 500/700 for
  display & wordmark (tracked in −0.015em). **Inter** 400/500/600 for body & UI.
  **Fraunces italic** 400/500 for the soul — *italic only, never upright, never
  body copy.* Headings use fluid `clamp()` sizes.
- **Backgrounds.** No photography in the system. The hero uses a **scattered
  starfield** (faint multi-radial-gradient nodes, intentionally off-center) and a
  large, very low-opacity (≈0.14) mark bleeding off the right edge. Otherwise:
  flat color fields. No big gradients as surfaces (the only gradient is *inside*
  the mark, lilac→gold).
- **Borders & cards.** Depth is carried by **surface color + hairline borders**,
  not shadows. Cards are indigo (on dark) or white (on paper) with a 1px
  lilac/violet hairline at low alpha, **14px** radius. The system is
  **near-shadowless** — a soft shadow token exists but is rarely used.
- **Radii.** 14px cards, 12px panels, 4px focus, **999px pills** (buttons, tags,
  notices), 26px app-tile.
- **Animation.** Restrained. Transitions ≈ `.15s ease`. Hover = **translateY
  lift** (−1px buttons, −3px cards), *not* a shadow or scale. Mobile nav reveals
  via `max-height .25s`. Everything is killed under
  `prefers-reduced-motion: reduce`. No bounces, no loops, no parallax.
- **Hover / press.** Links underline (3px offset, lilac). Buttons lift and
  lighten (gold → `#F7D488`). Cards lift and warm their border to lilac, surface
  to `#232A63`. No color-darkening press states; no shrink.
- **Transparency & blur.** The **sticky header** is the one glass surface:
  `rgba(14,18,48,.82)` + `blur(10px)` + a lilac hairline. Alpha lilac/gold/
  starlight washes (`.08`–`.40`) do tints, dividers, and focus rings.
- **Focus.** Always visible: **3px gold outline**, 2px offset, 4px rounding.
  Accessibility is load-bearing (skip links, `aria-current`, reduced-motion).
- **Imagery vibe.** Cool, dark, cosmic, calm — starlight on midnight, warmed by a
  single gold horizon. Never busy, never loud.
- **Layout.** Content column is `min(1080px, 92vw)`, gutter-aligned (not
  auto-centered text). Prose blocks cap at a 68ch measure. Sections breathe with
  fluid `clamp(3rem, 7vw, 5.5rem)` vertical padding.

---

## Iconography

Wiggleverse is **iconography-light by design**. There is **no icon font and no
icon set** in the codebase.

- **The mark** is the one true graphic: the *Circle of Equals*, shipped as SVG in
  four cuts — `wiggleverse-mark.svg` (lilac→gold gradient line, starlight nodes),
  `mark-mono-gold.svg` (footer), `mark-on-light.svg` (ink on paper), and
  `favicon.svg` (gold line + starlight nodes on a rounded-26px midnight tile).
  Raster favicons (`favicon-32.png`, `favicon-180.png`) are provided for tabs and
  iOS. All are in `assets/`.
- **"Icons" are geometric unicode glyphs.** The audience router uses
  **✧ ◇ ◈ ❍ ◐** as quiet, abstract door markers — never pictographic icons,
  never emoji. Treat these as the sanctioned glyph set when a small mark is
  needed. Arrows are literal `→` characters in link/button text.
- **No emoji, ever.** (Reconfirmed under Content fundamentals.)
- **If you need UI icons** (e.g. a richer product surface that the marketing site
  doesn't cover), there is no house set to match — keep them to a thin,
  geometric, single-weight line style consistent with the mark, and **flag the
  addition** so it can be folded into the brand properly. Do not hand-draw new
  brand illustrations.

---

## Index / manifest

Root files:

- `styles.css` — the global entry point (consumers link this one file). `@import`
  manifest only.
- `tokens/colors.css` · `tokens/typography.css` · `tokens/spacing.css` — CSS
  custom properties (base values + semantic aliases).
- `assets/` — the Circle-of-Equals marks (4 cuts), favicons, and the three
  vendored webfont families in `assets/fonts/` (+ `fonts.css` `@font-face`).
- `guidelines/` — foundation specimen cards (Colors, Type, Spacing, Brand).
- `SKILL.md` — Agent-Skills-compatible entry point.

Components (`window.WiggleverseDesignSystem_*`):

- **core/** — `Button`, `Tag`, `Notice`, `Eyebrow`, `Soul`, `Callout`
- **cards/** — `PathCard`, `BuildCard`
- **brand/** — `BrandLockup`
- **navigation/** — `SiteHeader`, `SiteFooter`

UI kits:

- **ui_kits/wiggleverse-www/** — high-fidelity recreation of the marketing site
  (Home, About, Ecomm, Finances/open-book), composing the components above.

Each component directory carries `<Name>.jsx`, `<Name>.d.ts`, `<Name>.prompt.md`,
and one `@dsCard` HTML thumbnail. Mount components in card/kit HTML via
`const { X } = window.WiggleverseDesignSystem_94cd80` after loading
`_ds_bundle.js` (generated automatically — do not edit).