t3-code-android-nightly/.repos/alchemy-effect/website/design-system/README.md

Alchemy Design System

Infrastructure-as-Effects — a TypeScript framework that unifies cloud infrastructure and application logic into a single type-safe program powered by Effect.

Alchemy is a developer-tool brand: terminal-first, code-dense, dark-mode only, with one signature color — mint green #00e599. Marketing moments lean on hand-drawn sketch diagrams (arrows, circles, scribbled labels) to explain abstract type-system concepts. Everything else is flat, quiet, and close to black.

This design system captures the visuals, tone, and components needed to ship new marketing pages, docs, social posts, and slide decks that feel like Alchemy — without re-inventing tokens each time.

---

Sources

• Repo: github.com/alchemy-run/alchemy — website (Astro + Starlight), README, docs content, raw sketch PNGs under images/.
• Live docs: https://alchemy.run
• Docs styling: website/src/styles/custom.css — the ground truth for color tokens, spacing, dark-only theme.
• Hero diagrams: images/alchemy-effect-*.png — hand-drawn Function → Binding → Resource triple, layers, terminal screenshots.
• Sibling repos (same brand): alchemy-run/distilled (Effect-native cloud SDKs).

---

Index

File / folder	What's in it
README.md	This doc — brand context, content & visual foundations, iconography
SKILL.md	Agent Skill manifest (usable standalone in Claude Code)
colors_and_type.css	All design tokens: colors, type, spacing, radii, shadows, motion
fonts/	Local webfont fallbacks (Inter, JetBrains Mono, Caveat via Google Fonts import)
assets/	Logos, hand-drawn diagrams, product screenshots
preview/	HTML specimen cards — one per token group / component cluster
ui_kits/website/	Marketing + docs UI kit (hero, feature grid, terminal, provider cards)
ui_kits/docs/	Docs reader UI kit (sidebar nav, article, code blocks, callouts)

Products covered

1. alchemy.run marketing site — landing, what-is, getting-started. Astro + Starlight.
2. alchemy.run docs — sidebar nav, MDX articles, expressive-code blocks, terminal widget.

No app UI exists — Alchemy is a CLI + library. The CLI's terminal output ($ alchemy deploy, colored plan/apply reports) is itself a visual surface and is recreated as a component.

---

Content Fundamentals

Alchemy's voice is technical, calm, and quietly opinionated. It talks to senior TypeScript engineers. It never hypes, never uses exclamation marks for emphasis, and never uses emoji outside the occasional Discord context.

Tone rules

• Lowercase brand name always: alchemy — not "Alchemy" in body copy (headings can capitalize for sentence case; the wordmark itself is always lowercase).
• Short declarative sentences. Max ~18 words. Break into paragraphs instead of running on.
• "You" for the reader, "we" for the team. "Come hang in our Discord." "You'll install Alchemy and Effect."
• Technical terms are the nouns. Capitalize product concepts when used as proper nouns: Stack, Resource, Provider, Binding, Layer, Output Attribute. Leave verbs lowercase: deploy, bind, yield.
• Code is a first-class citizen. Almost every paragraph either introduces a code block or refers to monospace identifiers. Don't paraphrase what the code shows — show it.
• No hype adjectives. Never say "amazing", "powerful", "revolutionary", "magical". Say what it does.
• Specific numbers > vague claims. "in under two minutes", "Node.js 22+", "under 30 minutes" — concrete, verifiable.
• Em-dashes (—) for rhetorical pivots; used frequently. Same character, no spaces around it sometimes, with spaces sometimes — match the docs.
• Tagline form: "X. Y." — two sentences, first is the category, second is the value. "Infrastructure-as-Effects. Your infrastructure and application logic in a single, type-safe program."

Casing

• Product name in prose: alchemy (lowercase)
• Headings: Sentence case — "Getting started", "What is alchemy?", "Plan, deploy, destroy"
• alchemy deploy, alchemy dev, alchemy destroy — CLI verbs lowercase
• TypeScript identifiers verbatim (Cloudflare.R2.Bucket, Effect.gen)

Don't

• ❌ Emoji in marketing / docs body copy
• ❌ Rhetorical questions as headings ("Why Alchemy?")
• ❌ Marketing filler ("we're excited to announce…")
• ❌ Capitalizing "Alchemy" mid-sentence
• ❌ Introducing a concept without a code example nearby

Representative copy

"Infrastructure as Effects. Your infrastructure and application logic in a single, type-safe program."

"If it compiles, it deploys."

_"Resources are just Effects. Resources are declared as Effects and composed with yield_. Import them from any file, bind them to Workers, pass their outputs to other resources — it's all just TypeScript."*

"Preview what will change with plan, apply it with deploy, and tear it down with destroy. Stages isolate environments so dev and prod never collide."

"alchemy is in alpha and not ready for production use (expect breaking changes). Come hang in our Discord to participate in the early stages of development."

---

Visual Foundations

Mode

Dark mode only. The color-scheme: dark declaration is hard-coded and the theme toggle is hidden. Every surface is on a near-black canvas. Do not produce light-mode variants unless explicitly asked — they don't exist.

Color

• One accent: #00e599 — a bright, slightly-yellow mint green. Used for emphasis, success states, CTAs, link hovers, the wordmark dot, and the single gradient stop in "Infrastructure as Effects" hero text.
• Canvas: #0a0a0a (page) → #111111 (nav/sidebar) → #18181b (elevated cards) → #1f1f23 (hover). Steps are ~1–2 lightness units apart — very subtle.
• Neutrals: Tailwind Zinc scale (50 → 950). Body text at zinc-200/300, muted at zinc-400, captions at zinc-500.
• Hairlines: rgba(255,255,255,0.06) for default borders, 0.10 for hover/emphasis. No solid-gray borders.
• Semantic colors in terminal output:
  • Success / create: #00e599 (same mint)
  • Update: #f5a524 (amber)
  • Replace / destroy: #f04b4b (red)
  • Info / tag: #7cc5ff (cyan)
  • Dim: #71717a

No purple. No blue gradients. No "SaaS violet". The only gradient in the entire brand is linear-gradient(90deg, #fff, #00e599) applied as background-clip: text on the word "Effects" in the hero.

Type

• Inter (400/500/600/700/800) — UI, headings, body
• JetBrains Mono (400/500/600) — all code, terminal output, eyebrows
• Caveat (600) — hand-drawn diagram labels (see Iconography)
• Letter-spacing: -0.04em on display, -0.02em on headings, 0 on body.
• Headings are sentence case, weight 700, tightly tracked. No all-caps except monospace eyebrows (EYEBROW TEXT, 12px, letter-spacing: 0.1em).

Spacing

• 4px grid: 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64 / 96.
• Section rhythm on marketing pages: margin-bottom: 5rem (80px) between hero / features / providers / CTA.
• Max content width on landing: 72rem (1152px).

Backgrounds

• Flat solid black-ish surfaces — no patterns, no noise, no gradients.
• Hand-drawn sketch illustrations are the signature decorative element — they appear as standalone hero artwork, not backgrounds. See Iconography.
• Occasional full-bleed terminal screenshots demonstrating CLI output.

Borders & cards

• Border radius: 8px standard (provider cards, buttons, code blocks), 4–6px for small chips/tags, 12px for large hero panels.
• Cards: background: #18181b; border: 1px solid rgba(255,255,255,0.06); border-radius: 8px; padding: 1.5rem;
• Never a colored left-border accent. Never an "alert callout" stripe.
• Hover on a card: border becomes var(--alc-accent). That's it — no transform, no shadow change, no scale.

Shadows

• Near-zero by default. Dark surfaces don't need elevation shadows.
• When used: 0 4px 14px rgba(0,0,0,0.5) for floating elements.
• Accent glow is allowed sparingly on focused/active CTA buttons: 0 0 0 1px rgba(0,229,153,.4), 0 0 24px -4px rgba(0,229,153,.4).

Transparency & blur

• Transparency is used for hairlines (rgba(255,255,255,.06–.16)) and accent washes (color-mix(in srgb, #00e599 12%, transparent)).
• No frosted-glass / backdrop-blur surfaces. Alchemy's surfaces are crisp and opaque.

Motion

• Restrained. Marketing page has essentially no animation. Hover transitions are 120–180ms ease on color/border only.
• Easing: cubic-bezier(0.2, 0, 0, 1) — standard Material out-curve.
• No bounces, no parallax, no auto-playing hero videos.
• Prefer instant state changes for developers — they move fast and dislike jank.

Hover states

• Links: color → var(--alc-accent).
• Cards with a link: border-color → var(--alc-accent). No translate.
• Primary buttons: background slightly brighter, no transform.
• Secondary buttons / icon buttons: background → rgba(255,255,255,.04).

Press / active states

• Buttons darken a touch (filter: brightness(0.95)) — no scale-down, no inset shadow. The goal is "it registered" without bouncing.

Focus states

• 2px mint outline, 2px offset. Never remove focus rings. outline: 2px solid #00e599; outline-offset: 2px;

Layout rules

• Fixed top nav (64px tall, #111 bg, hairline bottom border).
• Docs: 260px left sidebar (#111), article body max-width 768–820px, optional right-side "On this page" column.
• Marketing: centered, 72rem max-width, generous 5rem between sections.

Imagery vibe

• Hand-drawn, warm, slightly-silly sketches on otherwise austere dark surfaces. Black ink on white paper, dropped into the dark theme as-is (white backgrounds show through — it's a deliberate contrast).
• Product screenshots (VS Code, terminal) appear in their native github-dark-dimmed theme. Preserve as PNGs.
• No stock photography. No AI-generated imagery. No people.

Code blocks

• Theme: github-dark-dimmed (Expressive Code). Keyword #f47067, string #96d0ff, function #dcbdfb, type #6cb6ff, comment #768390.
• Filename header: small mono label at top-left, dim.
• Diff additions: green + prefix with row tint; deletions: red - prefix with row tint. TwoSlash-powered.

---

Iconography

Alchemy does not use an icon font or lucide/heroicons in its marketing or docs. The visual vocabulary splits into three categories:

1. Hand-drawn sketch illustrations (signature)

Black-ink marker sketches on white, scanned and dropped into the dark theme. Used for explaining concepts on the README and marketing site. They replace what would normally be iconographic diagrams.

Available in assets/:

• diagram-triple.png — Function → Binding → Resource (the core triple)
• diagram-triad.png — triad diagram
• diagram-layers.png — Effect Layer hierarchy sketch
• screenshot-plan-type.png — VS Code type-hover screenshot
• screenshot-output.png — VS Code stack output screenshot
• screenshot-policy-error.png — VS Code IAM policy type error

Typography in sketches: labels look like Caveat / marker handwriting. When recreating digitally, use Caveat 600 as the nearest Google Fonts match. Flag to the user that true sketches should be produced by hand or with an illustrator.

2. Code as decoration

The biggest "icons" on the marketing site are code blocks themselves. Every feature card has a syntax-highlighted TypeScript snippet paired with a short paragraph. Treat code blocks as the primary visual unit — size them, pad them, give them room.

3. CLI glyphs (terminal component)

Inside the custom <Terminal /> component, plain unicode / ASCII glyphs signal status:

• ✓ success (mint)
• + create (mint)
• ~ update (amber)
• - / × destroy (red)
• ◉ / ○ radio selection
• • bullet / separator (dim)
• [u]…[/u] underline markup, [b]…[/b] bold, [d]…[/d] dim, [g]…[/g] green/success, [c]…[/c] cyan

4. Small UI icons (Starlight built-ins)

The docs layout uses Starlight's stock icons — right-arrow, open-book, github, bun, npm, pnpm, seti:yarn — for link buttons and tabs. When recreating, use Lucide (CDN) as the closest stroke-weight match, or the original Starlight icons if available. Flag this substitution.

5. Logo mark

assets/logo-mark.svg — a mint dot on a rounded black square. This is a placeholder synthesized from the wordmark style on the live site; the repo does not contain an official logo file. Ask the user for a real logo asset.

Emoji usage: none in marketing/docs. Fine in community spaces (Discord) but out of scope for the design system.