# Genesis Design System

> *Design in the open.* — Genesis is a community platform where design engineers discover, share, and download production-ready design system files. The interface aesthetic is **editorial precision**: bold display typography, generous spacing, gallery-frame card surfaces, and indigo reserved strictly for interaction.

This repository **is** the design system — a compiler reads it and ships a runtime bundle + token index to consuming projects. Everything here is original work authored from the written brand brief.

---

## 1. Brand & product context

**Genesis** is a registry/community for design-system files (think "npm for design systems"). Developers browse a gallery of **kits** (Figma files, token sets, icon packs, React libraries), open a kit to see its versions and install command, and publish their own kits for community review.

- **Mood:** quietly confident, professional, modern — not sterile. High information density balanced by breathing room.
- **Signature brand element:** the homepage wordmark `DESIGN.md`, where `.md` is rendered in the one-and-only brand green. Green appears *nowhere else*.
- **Primary product surface:** the Genesis web platform (Explore gallery → Kit detail → Publish). Recreated in `ui_kits/genesis/`.

### Sources provided
- `uploads/logo-Astres.png` — an uploaded logo reading **"Astres Groupe Sarl"** (a blue/green globe mark). ⚠️ **This does not match the "Genesis" brand described in the brief.** It is preserved at `assets/logo-astres-provided.png` but is **not used** in the system. See *Caveats* — we need the real Genesis logo, or confirmation that the brand should be Astres.
- The written brand brief (colors, type, spacing, components, do's & don'ts) — this was the authoritative source and is fully encoded in `tokens/`.
- No codebase or Figma file was attached.

---

## 2. Content fundamentals (voice & tone)

- **Voice:** plain, confident, developer-to-developer. Short declaratives. Never salesy, never hypey.
- **Person:** addresses the reader as **"you"**; the platform refers to itself as **"we"** sparingly (e.g. *"We'll email you within 48 hours."*).
- **Casing:** Sentence case everywhere — headings, buttons, menu items. The only uppercase is the **overline** label style (`.gx-overline`, 11px, letter-spaced). Never Title Case buttons.
- **Punctuation:** real typographic characters — curly quotes (`"…"`), the em dash, and `·` middots as metadata separators (`Mara Ito · 12.4k downloads`).
- **Numbers:** abbreviated for stats (`12.4k`, not `12,400`). Versions are semver in mono (`1.4.0`).
- **Emoji:** **none.** Not part of the brand.
- **Examples of copy:**
  - Hero: *"Design in the open with DESIGN.md"* / *"Discover, share, and download production-ready design system files. Reviewed, versioned, and ready to drop into your stack."*
  - Empty state: *"This surface is part of the kit but left intentionally blank."*
  - Destructive confirm: *"This removes Editorial UI 1.4 and all its versions. This can't be undone."*
  - Microcopy is helpful and specific, never cute: *"Used in the install command — must be unique."*

---

## 3. Visual foundations

**Color.** Warm-neutral base (`#FAFAFA` page, `#FFFFFF` surfaces) with near-black text (`#0A0A0A` / `#6B6B6B`). **Indigo `#6366F1` is for interaction only** — CTAs, links, active states, focus rings — never decoration or static text. **Green `#20970B`** is reserved exclusively for the `DESIGN.md` highlight. Semantic colors (success/warning/error) appear only in status badges and validation. Never pure `#000`/`#fff` for text.

**Type.** Two-family contrast: **General Sans** (Fontshare) for display/headings — bold, tight tracking (−0.03 to −0.04em); **DM Sans** (Google) for all body/UI at 400/500; **JetBrains Mono** for code, versions, install commands, keyboard badges. Max two weights per screen. Scale: 72 / 60 / 32 / 24 / 15 / 13 / 12 / 11.

**Spacing & layout.** Strict 4px grid (4→96). Container max **1280px**, 24px gutters. Card grid gap 24px. Section rhythm 32 (mobile) / 48 / 64 (desktop).

**Backgrounds.** Flat warm gray. **No gradients, no illustrations, no imagery.** The single sanctioned decorative motif is the **interactive dot grid** (`radial-gradient(var(--border-strong) 1px, transparent 1px)` at 16px) — used behind kit previews. Kit preview thumbnails are abstract neutral **wireframe sketches** (grey rounded blocks), reading as a screenshot, not décor.

**Elevation.** Minimal. Cards rest **flat with a 1px `#E8E8EC` border**; on hover they lift **−2px** and gain `0 8px 30px rgba(0,0,0,.08)`. Primary buttons gain a tinted glow `0 4px 12px rgba(99,102,241,.35)` on hover. The nav uses **backdrop-blur** (`saturate(180%) blur(12px)` over `rgba(255,255,255,.72)`), not a shadow. Dropdowns/popovers/dialogs use `shadow-lg`. Never put a shadow on a static element.

**Borders & radius.** 4px (tags/chips/inline code) · 6px (buttons/inputs/selects) · 8px (panels/dropdowns) · 12px (kit cards/search bar/featured) · full (avatars/pills/status dots). Don't mix the 6px and 12px scales.

**Motion.** Restrained. 200ms standard (`cubic-bezier(0.2,0,0,1)`), 120ms for the button lift. Properties animated: background, box-shadow, transform, border-color. No bounces, no infinite loops, no entrance choreography on content.

**Hover / press states.** Buttons: primary darkens (`#6366F1`→`#4F46E5`) + glow + 1px lift; secondary/ghost get a `--surface-alt` wash; tags toggle to indigo fill. Nav links get a `--surface-alt` background. Press is conveyed by removing the lift (settle back to 0), not by shrinking.

**Transparency & blur.** Used only for the sticky nav backdrop and modal scrims (`rgba(10,10,10,.32)` + 2px blur). Not decorative.

**Focus.** A 3px indigo ring `0 0 0 3px rgba(99,102,241,.12)` with the border turning indigo — applied to inputs, search, and focusable controls.

---

## 4. Iconography

- **System:** a small, consistent **2px-stroke, round-cap line icon set**, drawn inline as SVG (24×24 viewBox, `currentColor`). Defined once in `ui_kits/genesis/primitives.jsx` (`ICONS` map: search, download, heart, plus, check, copy, chevron, layers, arrowRight, bell, upload, star). This matches the editorial, geometric feel and the Halo Icons kit the platform itself sells.
- **Style match:** equivalent to **Lucide / Feather** (2px stroke, rounded joins). If you need a broader set, link Lucide from CDN — it is visually identical to the in-house icons. *(Flagged substitution: no proprietary icon font existed to copy, so the line-icon style mirrors Lucide.)*
- **Emoji:** never used as icons.
- **Unicode:** only `⌘`, `·`, and the em dash appear as glyphs, in keyboard badges and metadata.
- **Logo assets:** `assets/genesis-logo.svg` (horizontal lockup) and `assets/genesis-glyph.svg` (the indigo "G" tile) — typographic marks built from the type system, since no official Genesis logo was supplied.

---

## 5. Index / manifest

**Root**
- `styles.css` — global entry point (consumers link this). `@import` lines only.
- `readme.md` — this file.
- `SKILL.md` — Agent Skill manifest for downloading & reusing the system.

**`tokens/`** — CSS custom properties, all reachable from `styles.css`.
- `fonts.css` (webfont @imports) · `colors.css` · `typography.css` · `spacing.css` · `elevation.css` (radius + shadow + motion) · `base.css` (light reset + element defaults).

**`components/`** — reusable React primitives (15). Each dir has `<Name>.jsx`, `<Name>.d.ts`, a `*.prompt.md`, and a `*.card.html` specimen.
- `buttons/` — **Button**, **IconButton**
- `forms/` — **Input**, **Select**, **Checkbox**, **Switch**, **SearchBar**
- `data-display/` — **Card**, **KitCard**, **Badge**, **Tag**, **Avatar**
- `navigation/` — **Tabs**
- `feedback/` — **Dialog**, **Toast**

**`ui_kits/genesis/`** — the Genesis platform recreation (self-contained, runs standalone).
- `index.html` (Explore homepage + starting point) · `data.js` · `primitives.jsx` (local mirror of the component library + icons) · `screens.jsx` (Navbar, Hero, Explore, Kit detail) · `upload.jsx` (Publish flow + ⌘K command palette) · `app.jsx` (routing shell).
- Flows: Explore gallery → open a kit → versions + install command; ⌘K search palette; Publish-a-kit form with review submission toast.

**`guidelines/`** — foundation specimen cards rendered in the Design System tab (Colors, Type, Spacing, Brand).

**`assets/`** — logos & marks.

**Starting points:** `Button`, `KitCard`, `SearchBar` (components) and the Genesis platform screen.

---

## 6. Caveats / open questions
- ⚠️ **Logo mismatch.** The uploaded logo is "Astres Groupe Sarl"; the brief describes "Genesis." We built Genesis with a typographic wordmark. **Please confirm the brand name and upload the real Genesis logo** (or tell us if it's actually Astres).
- **Fonts load from CDN** (Fontshare + Google), not self-hosted binaries. For offline/production self-hosting, upload the `.woff2` files.
- **Icons** mirror the Lucide line-icon style (no proprietary set was provided).
