| 1 | # Alchemy Design System |
| 2 | |
| 3 | > **Infrastructure-as-Effects** — a TypeScript framework that unifies cloud |
| 4 | > infrastructure and application logic into a single type-safe program |
| 5 | > powered by [Effect](https://effect.website). |
| 6 | |
| 7 | Alchemy is a developer-tool brand: terminal-first, code-dense, dark-mode only, |
| 8 | with one signature color — mint green `#00e599`. Marketing moments lean on |
| 9 | **hand-drawn sketch diagrams** (arrows, circles, scribbled labels) to explain |
| 10 | abstract type-system concepts. Everything else is flat, quiet, and close to |
| 11 | black. |
| 12 | |
| 13 | This design system captures the visuals, tone, and components needed to ship |
| 14 | new marketing pages, docs, social posts, and slide decks that feel like |
| 15 | Alchemy — without re-inventing tokens each time. |
| 16 | |
| 17 | --- |
| 18 | |
| 19 | ## Sources |
| 20 | |
| 21 | - **Repo:** `github.com/alchemy-run/alchemy` — website (Astro + |
| 22 | Starlight), README, docs content, raw sketch PNGs under `images/`. |
| 23 | - **Live docs:** https://alchemy.run |
| 24 | - **Docs styling:** `website/src/styles/custom.css` — the ground truth for |
| 25 | color tokens, spacing, dark-only theme. |
| 26 | - **Hero diagrams:** `images/alchemy-effect-*.png` — hand-drawn |
| 27 | Function → Binding → Resource triple, layers, terminal screenshots. |
| 28 | - **Sibling repos** (same brand): |
| 29 | `alchemy-run/distilled` (Effect-native cloud SDKs). |
| 30 | |
| 31 | --- |
| 32 | |
| 33 | ## Index |
| 34 | |
| 35 | | File / folder | What's in it | |
| 36 | | --------------------- | ------------------------------------------------------------------------------- | |
| 37 | | `README.md` | This doc — brand context, content & visual foundations, iconography | |
| 38 | | `SKILL.md` | Agent Skill manifest (usable standalone in Claude Code) | |
| 39 | | `colors_and_type.css` | All design tokens: colors, type, spacing, radii, shadows, motion | |
| 40 | | `fonts/` | Local webfont fallbacks (Inter, JetBrains Mono, Caveat via Google Fonts import) | |
| 41 | | `assets/` | Logos, hand-drawn diagrams, product screenshots | |
| 42 | | `preview/` | HTML specimen cards — one per token group / component cluster | |
| 43 | | `ui_kits/website/` | Marketing + docs UI kit (hero, feature grid, terminal, provider cards) | |
| 44 | | `ui_kits/docs/` | Docs reader UI kit (sidebar nav, article, code blocks, callouts) | |
| 45 | |
| 46 | ### Products covered |
| 47 | |
| 48 | 1. **alchemy.run marketing site** — landing, what-is, getting-started. Astro + Starlight. |
| 49 | 2. **alchemy.run docs** — sidebar nav, MDX articles, expressive-code blocks, terminal widget. |
| 50 | |
| 51 | No app UI exists — Alchemy is a CLI + library. The CLI's terminal output |
| 52 | (`$ alchemy deploy`, colored plan/apply reports) is itself a visual surface |
| 53 | and is recreated as a component. |
| 54 | |
| 55 | --- |
| 56 | |
| 57 | ## Content Fundamentals |
| 58 | |
| 59 | Alchemy's voice is **technical, calm, and quietly opinionated**. It talks to |
| 60 | senior TypeScript engineers. It never hypes, never uses exclamation marks for |
| 61 | emphasis, and never uses emoji outside the occasional Discord context. |
| 62 | |
| 63 | **Tone rules** |
| 64 | |
| 65 | - **Lowercase brand name** always: _alchemy_ — not "Alchemy" in body copy |
| 66 | (headings can capitalize for sentence case; the wordmark itself is always |
| 67 | lowercase). |
| 68 | - **Short declarative sentences.** Max ~18 words. Break into paragraphs |
| 69 | instead of running on. |
| 70 | - **"You" for the reader, "we" for the team.** "Come hang in our Discord." |
| 71 | "You'll install Alchemy and Effect." |
| 72 | - **Technical terms are the nouns.** Capitalize product concepts when used |
| 73 | as proper nouns: _Stack_, _Resource_, _Provider_, _Binding_, _Layer_, |
| 74 | _Output Attribute_. Leave verbs lowercase: _deploy_, _bind_, _yield_. |
| 75 | - **Code is a first-class citizen.** Almost every paragraph either |
| 76 | introduces a code block or refers to `monospace identifiers`. Don't |
| 77 | paraphrase what the code shows — show it. |
| 78 | - **No hype adjectives.** Never say "amazing", "powerful", "revolutionary", |
| 79 | "magical". Say what it does. |
| 80 | - **Specific numbers > vague claims.** "in under two minutes", "Node.js 22+", |
| 81 | "under 30 minutes" — concrete, verifiable. |
| 82 | - **Em-dashes (—) for rhetorical pivots**; used frequently. Same character, |
| 83 | no spaces around it sometimes, with spaces sometimes — match the docs. |
| 84 | - **Tagline form:** "**X.** Y." — two sentences, first is the category, second |
| 85 | is the value. _"Infrastructure-as-Effects. Your infrastructure and |
| 86 | application logic in a single, type-safe program."_ |
| 87 | |
| 88 | **Casing** |
| 89 | |
| 90 | - Product name in prose: **alchemy** (lowercase) |
| 91 | - Headings: **Sentence case** — "Getting started", "What is alchemy?", |
| 92 | "Plan, deploy, destroy" |
| 93 | - `alchemy deploy`, `alchemy dev`, `alchemy destroy` — CLI verbs lowercase |
| 94 | - TypeScript identifiers verbatim (`Cloudflare.R2.Bucket`, `Effect.gen`) |
| 95 | |
| 96 | **Don't** |
| 97 | |
| 98 | - ❌ Emoji in marketing / docs body copy |
| 99 | - ❌ Rhetorical questions as headings ("Why Alchemy?") |
| 100 | - ❌ Marketing filler ("we're excited to announce…") |
| 101 | - ❌ Capitalizing "Alchemy" mid-sentence |
| 102 | - ❌ Introducing a concept without a code example nearby |
| 103 | |
| 104 | **Representative copy** |
| 105 | |
| 106 | > _"Infrastructure as **Effects**. Your infrastructure and application logic in |
| 107 | > a single, type-safe program."_ |
| 108 | > |
| 109 | > _"If it compiles, it deploys."_ |
| 110 | > |
| 111 | > _"Resources are just Effects. Resources are declared as Effects and |
| 112 | > composed with `yield_`. Import them from any file, bind them to Workers, |
| 113 | > pass their outputs to other resources — it's all just TypeScript."\* |
| 114 | > |
| 115 | > _"Preview what will change with `plan`, apply it with `deploy`, and tear |
| 116 | > it down with `destroy`. Stages isolate environments so `dev` and `prod` |
| 117 | > never collide."_ |
| 118 | > |
| 119 | > _"alchemy is in alpha and not ready for production use (expect breaking |
| 120 | > changes). Come hang in our Discord to participate in the early stages of |
| 121 | > development."_ |
| 122 | |
| 123 | --- |
| 124 | |
| 125 | ## Visual Foundations |
| 126 | |
| 127 | ### Mode |
| 128 | |
| 129 | **Dark mode only.** The `color-scheme: dark` declaration is hard-coded and |
| 130 | the theme toggle is hidden. Every surface is on a near-black canvas. Do |
| 131 | not produce light-mode variants unless explicitly asked — they don't exist. |
| 132 | |
| 133 | ### Color |
| 134 | |
| 135 | - **One accent:** `#00e599` — a bright, slightly-yellow mint green. Used for |
| 136 | emphasis, success states, CTAs, link hovers, the wordmark dot, and the |
| 137 | single gradient stop in "Infrastructure as **Effects**" hero text. |
| 138 | - **Canvas:** `#0a0a0a` (page) → `#111111` (nav/sidebar) → `#18181b` (elevated |
| 139 | cards) → `#1f1f23` (hover). Steps are ~1–2 lightness units apart — very |
| 140 | subtle. |
| 141 | - **Neutrals:** Tailwind Zinc scale (50 → 950). Body text at zinc-200/300, |
| 142 | muted at zinc-400, captions at zinc-500. |
| 143 | - **Hairlines:** `rgba(255,255,255,0.06)` for default borders, `0.10` for |
| 144 | hover/emphasis. No solid-gray borders. |
| 145 | - **Semantic colors in terminal output:** |
| 146 | - Success / create: `#00e599` (same mint) |
| 147 | - Update: `#f5a524` (amber) |
| 148 | - Replace / destroy: `#f04b4b` (red) |
| 149 | - Info / tag: `#7cc5ff` (cyan) |
| 150 | - Dim: `#71717a` |
| 151 | |
| 152 | **No purple. No blue gradients. No "SaaS violet".** The only gradient in the |
| 153 | entire brand is `linear-gradient(90deg, #fff, #00e599)` applied as |
| 154 | `background-clip: text` on the word "Effects" in the hero. |
| 155 | |
| 156 | ### Type |
| 157 | |
| 158 | - **Inter** (400/500/600/700/800) — UI, headings, body |
| 159 | - **JetBrains Mono** (400/500/600) — all code, terminal output, eyebrows |
| 160 | - **Caveat** (600) — hand-drawn diagram labels (see Iconography) |
| 161 | - Letter-spacing: `-0.04em` on display, `-0.02em` on headings, `0` on body. |
| 162 | - Headings are **sentence case**, weight 700, tightly tracked. No all-caps |
| 163 | except monospace eyebrows (`EYEBROW TEXT`, 12px, `letter-spacing: 0.1em`). |
| 164 | |
| 165 | ### Spacing |
| 166 | |
| 167 | - 4px grid: 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64 / 96. |
| 168 | - Section rhythm on marketing pages: `margin-bottom: 5rem` (80px) between |
| 169 | hero / features / providers / CTA. |
| 170 | - Max content width on landing: `72rem` (1152px). |
| 171 | |
| 172 | ### Backgrounds |
| 173 | |
| 174 | - **Flat solid black-ish surfaces** — no patterns, no noise, no gradients. |
| 175 | - **Hand-drawn sketch illustrations** are the signature decorative element — |
| 176 | they appear as standalone hero artwork, not backgrounds. See Iconography. |
| 177 | - Occasional full-bleed terminal screenshots demonstrating CLI output. |
| 178 | |
| 179 | ### Borders & cards |
| 180 | |
| 181 | - Border radius: **8px** standard (provider cards, buttons, code blocks), |
| 182 | **4–6px** for small chips/tags, **12px** for large hero panels. |
| 183 | - Cards: `background: #18181b; border: 1px solid rgba(255,255,255,0.06); |
| 184 | border-radius: 8px; padding: 1.5rem;` |
| 185 | - **Never** a colored left-border accent. Never an "alert callout" stripe. |
| 186 | - Hover on a card: border becomes `var(--alc-accent)`. That's it — no |
| 187 | transform, no shadow change, no scale. |
| 188 | |
| 189 | ### Shadows |
| 190 | |
| 191 | - Near-zero by default. Dark surfaces don't need elevation shadows. |
| 192 | - When used: `0 4px 14px rgba(0,0,0,0.5)` for floating elements. |
| 193 | - **Accent glow** is allowed sparingly on focused/active CTA buttons: |
| 194 | `0 0 0 1px rgba(0,229,153,.4), 0 0 24px -4px rgba(0,229,153,.4)`. |
| 195 | |
| 196 | ### Transparency & blur |
| 197 | |
| 198 | - Transparency is used for **hairlines** (`rgba(255,255,255,.06–.16)`) and |
| 199 | **accent washes** (`color-mix(in srgb, #00e599 12%, transparent)`). |
| 200 | - No frosted-glass / backdrop-blur surfaces. Alchemy's surfaces are crisp |
| 201 | and opaque. |
| 202 | |
| 203 | ### Motion |
| 204 | |
| 205 | - **Restrained.** Marketing page has essentially no animation. Hover |
| 206 | transitions are `120–180ms ease` on color/border only. |
| 207 | - Easing: `cubic-bezier(0.2, 0, 0, 1)` — standard Material out-curve. |
| 208 | - No bounces, no parallax, no auto-playing hero videos. |
| 209 | - Prefer instant state changes for developers — they move fast and dislike |
| 210 | jank. |
| 211 | |
| 212 | ### Hover states |
| 213 | |
| 214 | - **Links:** color → `var(--alc-accent)`. |
| 215 | - **Cards with a link:** border-color → `var(--alc-accent)`. No translate. |
| 216 | - **Primary buttons:** background slightly brighter, no transform. |
| 217 | - **Secondary buttons / icon buttons:** background → `rgba(255,255,255,.04)`. |
| 218 | |
| 219 | ### Press / active states |
| 220 | |
| 221 | - Buttons darken a touch (`filter: brightness(0.95)`) — no scale-down, no |
| 222 | inset shadow. The goal is "it registered" without bouncing. |
| 223 | |
| 224 | ### Focus states |
| 225 | |
| 226 | - **2px mint outline, 2px offset.** Never remove focus rings. |
| 227 | `outline: 2px solid #00e599; outline-offset: 2px;` |
| 228 | |
| 229 | ### Layout rules |
| 230 | |
| 231 | - Fixed top nav (64px tall, `#111` bg, hairline bottom border). |
| 232 | - Docs: 260px left sidebar (`#111`), article body max-width 768–820px, |
| 233 | optional right-side "On this page" column. |
| 234 | - Marketing: centered, 72rem max-width, generous 5rem between sections. |
| 235 | |
| 236 | ### Imagery vibe |
| 237 | |
| 238 | - **Hand-drawn, warm, slightly-silly sketches** on otherwise austere dark |
| 239 | surfaces. Black ink on white paper, dropped into the dark theme as-is |
| 240 | (white backgrounds show through — it's a deliberate contrast). |
| 241 | - Product screenshots (VS Code, terminal) appear in their native |
| 242 | github-dark-dimmed theme. Preserve as PNGs. |
| 243 | - No stock photography. No AI-generated imagery. No people. |
| 244 | |
| 245 | ### Code blocks |
| 246 | |
| 247 | - **Theme:** `github-dark-dimmed` (Expressive Code). Keyword `#f47067`, string |
| 248 | `#96d0ff`, function `#dcbdfb`, type `#6cb6ff`, comment `#768390`. |
| 249 | - **Filename header:** small mono label at top-left, dim. |
| 250 | - **Diff additions:** green `+` prefix with row tint; deletions: red `-` |
| 251 | prefix with row tint. TwoSlash-powered. |
| 252 | |
| 253 | --- |
| 254 | |
| 255 | ## Iconography |
| 256 | |
| 257 | **Alchemy does not use an icon font or lucide/heroicons in its marketing |
| 258 | or docs.** The visual vocabulary splits into three categories: |
| 259 | |
| 260 | ### 1. Hand-drawn sketch illustrations (signature) |
| 261 | |
| 262 | Black-ink marker sketches on white, scanned and dropped into the dark |
| 263 | theme. Used for explaining concepts on the README and marketing site. They |
| 264 | replace what would normally be iconographic diagrams. |
| 265 | |
| 266 | Available in `assets/`: |
| 267 | |
| 268 | - `diagram-triple.png` — **Function → Binding → Resource** (the core triple) |
| 269 | - `diagram-triad.png` — triad diagram |
| 270 | - `diagram-layers.png` — Effect Layer hierarchy sketch |
| 271 | - `screenshot-plan-type.png` — VS Code type-hover screenshot |
| 272 | - `screenshot-output.png` — VS Code stack output screenshot |
| 273 | - `screenshot-policy-error.png` — VS Code IAM policy type error |
| 274 | |
| 275 | **Typography in sketches:** labels look like Caveat / marker handwriting. |
| 276 | When recreating digitally, use **Caveat 600** as the nearest Google Fonts |
| 277 | match. Flag to the user that true sketches should be produced by hand or |
| 278 | with an illustrator. |
| 279 | |
| 280 | ### 2. Code as decoration |
| 281 | |
| 282 | The biggest "icons" on the marketing site are **code blocks themselves**. |
| 283 | Every feature card has a syntax-highlighted TypeScript snippet paired with |
| 284 | a short paragraph. Treat code blocks as the primary visual unit — size |
| 285 | them, pad them, give them room. |
| 286 | |
| 287 | ### 3. CLI glyphs (terminal component) |
| 288 | |
| 289 | Inside the custom `<Terminal />` component, plain unicode / ASCII glyphs |
| 290 | signal status: |
| 291 | |
| 292 | - `✓` success (mint) |
| 293 | - `+` create (mint) |
| 294 | - `~` update (amber) |
| 295 | - `-` / `×` destroy (red) |
| 296 | - `◉` / `○` radio selection |
| 297 | - `•` bullet / separator (dim) |
| 298 | - `[u]…[/u]` underline markup, `[b]…[/b]` bold, `[d]…[/d]` dim, `[g]…[/g]` |
| 299 | green/success, `[c]…[/c]` cyan |
| 300 | |
| 301 | ### 4. Small UI icons (Starlight built-ins) |
| 302 | |
| 303 | The docs layout uses Starlight's stock icons — `right-arrow`, `open-book`, |
| 304 | `github`, `bun`, `npm`, `pnpm`, `seti:yarn` — for link buttons and tabs. |
| 305 | When recreating, **use Lucide** (CDN) as the closest stroke-weight match, |
| 306 | or the original Starlight icons if available. Flag this substitution. |
| 307 | |
| 308 | ### 5. Logo mark |
| 309 | |
| 310 | `assets/logo-mark.svg` — a mint dot on a rounded black square. This is a |
| 311 | **placeholder** synthesized from the wordmark style on the live site; the |
| 312 | repo does not contain an official logo file. **Ask the user for a real |
| 313 | logo asset.** |
| 314 | |
| 315 | Emoji usage: **none** in marketing/docs. Fine in community spaces |
| 316 | (Discord) but out of scope for the design system. |