Design System Specification

Sema Brand Identity

Canonical style guide for the Sema Lisp programming language, computational notebook, and CLI toolchain. Built around warm dark architectures, gold emphasis, and functional typography.

Design Philosophy

Sema's identity reflects a modern, warm, and highly structured environment. It merges the mechanical precision of an s-expression evaluator with the organic fluency of LLM integration. Interfaces should feel like a premium text editor—focused, dark, and visually stable.

Warm Architectural Dark

Interfaces are constructed from layered dark values, simulating physical depth. We avoid harsh #000 black and bright white borders.

Accent as Focus

Gold is used sparingly as a high-contrast focus and status color. It draws the eye to running operations, active lines, and key indicators.

02

Typography & Specimen

Sema relies on a strict dual-font layout system. We use Cormorant (serif) for editorial headings and branding elements, and JetBrains Mono (monospace) for technical indicators, syntax nodes, and CLI instructions. Inter provides clean body prose.

Cormorant — Editorial & Headings

Aa Bb Cc Dd Ee Ff Gg Hh Ii Jj Kk Ll Mm Nn Oo Pp Qq Rr Ss Tt Uu Vv Ww Xx Yy Zz
Heading 1 · 300 Light
The future of programming is conversational
Heading 2 · 300 Light
Evaluation as a dialogical loop
Heading 3 · 500 Medium
Special Forms & Native Evaluator

JetBrains Mono — Syntax & Code

Aa Bb Cc Dd Ee Ff Gg Hh Ii Jj Kk Ll Mm Nn Oo Pp Qq Rr Ss Tt Uu Vv Ww Xx Yy Zz 1234567890
Code Block · 400 Regular
(defagent coder {:model "claude-haiku-4-5" :system "Rust programmer"})
Code Small · 400 Regular
(map (lambda (x) (* x 2)) (range 1 10)) ; => (2 4 6 8 10 12 14 16 18)

Inter — UI & Body Prose

Aa Bb Cc Dd Ee Ff Gg Hh Ii Jj Kk Ll Mm Nn Oo Pp Qq Rr Ss Tt Uu Vv Ww Xx Yy Zz 1234567890
Body Prose · 400 Regular
Sema Lisp merges the speed of Rust with the power of modern LLMs. It is designed to be highly structured, conversationally persistent, and fully sandboxed.
UI Label · 500 Medium
Active Session: coder-agent (llm-run-active)
03

Prose & Editorial Idioms

Consistent layouts for storytelling and editorial blocks used across marketing pages and major documentation entries.

A. The Objection Header (Kicker)

“Wait — a Lisp?”

You won't write most of it anyway.

Your coding agent will. And a Lisp is the language with the least surface for an agent to be wrong about—see the open-source repository to review the complete language specifications.

B. The Claims List with Highlights (.claims & <mark>)
  • Sixty years of training data. Lisp predates nearly everything else in the corpus. Scheme, Common Lisp, Clojure, Racket — your agent has read all of it, and a Lisp is a Lisp. Review the design philosophy.
  • The whole language fits in context. Point your agent at llms.txt — where Sema diverges from the dialects it already knows, and nothing else. Constraints, not a textbook.
C. The Chevron List (.ship-list)
  • Minimal footprint. The entire compiler and VM is a single statically linked binary with zero external runtime dependencies.
  • Instant startup. VM boots in less than 1ms. Fast enough for serverless functions and ephemeral CLI invocations.
04

Color Palette

Colors are structured entirely in a deep, warm dark palette. Click any swatch card below to copy its CSS value to your clipboard.

variables.css
:root {
  --gold: #c8a855;
  --gold-dim: rgba(200, 168, 85, 0.5);
  --gold-glow: rgba(200, 168, 85, 0.08);
  --gold-soft: rgba(200, 168, 85, 0.14);
  --bg: #131110;
  --bg-elevated: #181512;
  --bg-editor: #1c1916;
  --bg-output: #0f0d0c;
  --text-primary: #e9e3d6;
  --text-secondary: #968c79;
  --text-tertiary: #6b6354;
  --border: #2b2620;
  --border-focus: #c8a855;
  --success: #6a9955;
  --error: #c85555;
}
ColorVariableValues / FormatsRole & Application
Accent & Opacity Scales
--gold
hex: #c8a855
oklch: oklch(73.57% 0.144 85.34)
rgba: rgba(200, 168, 85, 1)
Primary accent, CTA, links, active states, key keywords.
--gold-dim
hex: rgba(200, 168, 85, 0.5)
oklch: oklch(73.57% 0.144 85.34 / 0.5)
rgba: rgba(200, 168, 85, 0.5)
Transparent borders, stale/inactive indicators.
--gold-glow
hex: rgba(200, 168, 85, 0.08)
oklch: oklch(73.57% 0.144 85.34 / 0.08)
rgba: rgba(200, 168, 85, 0.08)
Hover backgrounds on interactive rows.
--gold-soft
hex: rgba(200, 168, 85, 0.14)
oklch: oklch(73.57% 0.144 85.34 / 0.14)
rgba: rgba(200, 168, 85, 0.14)
Selection overlay background.
Background Hierarchy
--bg
hex: #131110
oklch: oklch(10.57% 0.007 68.32)
rgba: rgba(19, 17, 16, 1)
Page canvas, sidebar background, main window.
--bg-elevated
hex: #181512
oklch: oklch(12.21% 0.012 71.95)
rgba: rgba(24, 21, 18, 1)
Cards, toolbars, raised surfaces, modals.
--bg-editor
hex: #1c1916
oklch: oklch(13.75% 0.014 74.45)
rgba: rgba(28, 25, 22, 1)
Code editing areas, text inputs, focused blocks.
--bg-output
hex: #0f0d0c
oklch: oklch(8.65% 0.006 68.32)
rgba: rgba(15, 13, 12, 1)
Deepest level. Output panels, read-only consoles.
Typography & Text
--text-primary
hex: #e9e3d6
oklch: oklch(91.31% 0.021 78.43)
rgba: rgba(233, 227, 214, 1)
Body copy on marketing pages, primary headings.
--text-secondary
hex: #968c79
oklch: oklch(60.91% 0.025 80.24)
rgba: rgba(150, 140, 121, 1)
Standard UI labels, secondary headings, editor text.
--text-tertiary
hex: #6b6354
oklch: oklch(44.89% 0.022 79.52)
rgba: rgba(107, 99, 84, 1)
Muted comments, captions, disabled states.
Structure & Borders
--border
hex: #2b2620
oklch: oklch(19.34% 0.015 76.51)
rgba: rgba(43, 38, 32, 1)
Default borders, dividers, subtle structure.
--border-focus
hex: #c8a855
oklch: oklch(73.57% 0.144 85.34)
rgba: rgba(200, 168, 85, 1)
Highlighted/focused borders.
Semantic Status
--success
hex: #6a9955
oklch: oklch(60.67% 0.117 138.83)
rgba: rgba(106, 153, 85, 1)
Success indicators, green highlights.
--error
hex: #c85555
oklch: oklch(53.25% 0.163 24.31)
rgba: rgba(200, 85, 85, 1)
Error messages, validation alerts.
05

Depth, Spacing & Radius

Sema represents visual hierarchy by layered background darkness and border boundaries, rather than drop shadows.

Elevation Levels

Page Canvas (--bg)
#131110
The main base viewport. Sidebars and status bars.
Surface (--bg-elevated)
#181512
Toolbars, feature cards, and modals. Sits directly above the canvas.
Editor Focus (--bg-editor)
#1c1916
Code input areas. Active indicators use 3px solid gold border.
Output Panel (--bg-output)
#0f0d0c
Deepest visual layer. Embedded execution consoles.

Border Radius Scale

sm 3px
md 4px
lg 6px
xl 8px
pill 20px

Spacing Scale

xs (4px)
sm (8px)
md (16px)
lg (24px)
xl (32px)
2xl (48px)
06

UI Kit Components

Reference implementations of common user interface elements rendered using active system tokens.

Buttons & Actions

button-primary
button-secondary
button-run
button-ghost
button-pill
button-debug

Cards, Tags & Notebook Elements

card-feature

Tail-Call Optimized

Trampoline-based tree evaluator. Execute deeply recursive functions without heap exhaustion.

tags (provider & function)
AnthropicOpenAIstring/splitllm/complete
notebook-cell (active)
[1]
(defagent coder {:model "claude-3-5"})
notebook-cell (stale / inactive)
[2*]
(agent/run coder "Hello world") ; stale output
output-panel
Executing compilation... done.
42
Error: symbol 'x' is unbound in environment
14ms · $0.00004

Comparison Code Panes

Code specimens rendering on the website. Features two variations: a standard/accentless pane (used for standard Python or foreign SDKs) and an accented, active gold glow pane (used for Sema native files).

agent.py — Python + SDKyou write the machinery
import anthropic

client = anthropic.Anthropic()
resp = client.messages.create(
    model="claude-3-5-sonnet",
    max_tokens=1024,
    messages=[{"role": "user", "content": "hello"}]
)
Standard pane container using neutral borders (#2b2620) and standard raised background (#181512) without glows.
agent.sema — Semathe machinery is the language
(defagent coder
  {:system    "You are a coding assistant."
   :tools     [read-file run-command]
   :max-turns 10})
Accented active container using a gold border (var(--gold-line)) and a subtle gold ambient shadow glow.
07

Syntax Highlighting

Comparison between marketing/docs pages and the interactive playground environment, detailing target token styles.

Website Style

;; Define a tool the LLM can call(deftool get-weather "Get weather for a city"{:city {:type :string}}(lambda (city)(format "~a: 22°C, sunny" city)))

Playground Style

;; Define a tool the LLM can call(deftool get-weather "Get weather for a city"{:city {:type :string}}(lambda (city)(format "~a: 22°C, sunny" city)))
TokenWebsitePlaygroundCanonical TargetConvergence Rationale
Comment#5a5a4a#6b6354#6b6354Unified with tertiary typography scale
Keyword#d4a052#c8a855#c8a855Use standard gold variable for core special forms
String#8aaa6a#a8c47a#a8c47aBrighter green provides better contrast on warm darks
Number#d08a60#d19a66#d19a66Consistent with modern dark editor configurations
Keyword Lit#c89050#7aacb8#7aacb8Muted blue distinguishes :symbols and options from core code
Paren#444438#6a6258#6a6258Clear layout structure without distracting visual clutter
08

Icon Showcase & Spec

Comparison between the old serif "S" assets and the new parenthesized (s) or (sema) specifications, showing custom indicators for file types.

Favicon / Canonical Mark (32×32)

Rounded square logo badge. Left: Old Georgia serif style. Right: New parenthesized brand mark.

S
(s)

Sema Source File (.sema, 16×16)

Standard file association icon. Left: Old Georgia Serif 'S'. Right: New parenthesized 's' indicating Lisp origins.

S
(s)

Sema Compiled Bytecode (.semac, 16×16)

Compiled runtime artifact. Bottom-right modifier is a solid gold circle containing a dark 'c'. Base logo is grayed to suggest a compiled asset.

Sc
(s)c

Sema Notebook File (.sema-nb, 16×16)

Computational notebook layout file. Bottom-right modifier is a clean gold double-line cell preview layout outline.

S
(s)

Notebook cells & execution variants

Alternative outline representations of active notebook cells and play/runtime conditions.

S
(s)
S
(s)

Transparent File Explorer Icons

High-fidelity, transparent-background variants optimized for file trees in IDEs (like VS Code, Zed, and IntelliJ). Each ships a light and dark variant — the glyph flips ink so it stays legible on any editor theme. Shown light / dark side by side below.

.sema
(s)
Light
(s)
Dark
.semac
(s)c
Light
(s)c
Dark
.sema-nb
(s)
Light
(s)
Dark
IDE Filetree Showcase
EXPLORER: SEMA-PROJECT
›📂crates
›📂examples
(s)hello.sema
(s)agent.sema
›📂notebooks
(s)research.sema-nb
›📂target
(s)chello.semac

Notebook Icon Candidates parked

Exploratory notebook marks in the new transparent (s) style — not yet shipped in any product, kept here for future use (notebook actions, tool-window icons). Dark-theme glyph shown; pair with a light variant when wired up.

A · Page
(s)
B · Play
(s)
C · Stacked
(s)
D · Full page
(s)
E · Cell lines
(s)

Cross-Platform App Icon Guidelines

When packaging Sema integrations, extensions, or applications for various marketplaces, adhere to the following platform specifications:

App Store (iOS / macOS)
  • iOS: Must be flat square PNG (1024x1024). Transparency is forbidden; the system dynamically masks corners using a squircle.
  • macOS: Transparency and subtle drop shadows are permitted. Recommends a tilted, dimensional sheet style.
Google Play (Android)
  • Adaptive Icons: Requires separate background (512x512, safe zone 66%) and foreground layers to allow system-level parallax.
  • Masking: Flat square uploads are automatically masked to circles, squircles, or rounded rects.
VS Code Extension Marketplace
  • Proportions: 128x128px (or larger square e.g., 256x256). Transparent backgrounds are highly recommended.
  • Contrast: Design must remain highly visible against both the default light and dark theme header colors.
JetBrains Marketplace
  • Plugin Icon: 40x40px (or 80x80px for high-DPI). Vector SVG format is preferred.
  • Style: Simple, high-contrast flat shapes. Avoid tiny text or highly detailed ornaments.
09

Project Inventory

List of public domains, repositories, packages, and internal crates within the Sema workspace.

Public Surfaces

SurfaceURL / IdentifierRole & Deployment
Websitesema-lang.comMarketing site and documentation (VitePress, deployed via Vercel)
Playgroundsema.runInteractive browser REPL and debugger (vanilla JS, deployed via Vercel)
Package Registrypkg.sema-lang.comCommunity package registry API (Rust, Axum, SQLite)
GitHub Repositorygithub.com/HelgeSverre/semaPrimary codebase repository (Cargo multi-crate workspace)
Homebrew Cratehelgesverre/tap/sema-langFormula for standard macOS command-line installation
Cargo Cratesema-langcrates.io package hosting the main CLI executable and local REPL

Crate Workspace Structure

Crate NameResponsibility & Architectural Layer
sema-coreNaN-boxed Value primitive, Environment (Rc+RefCell), Env callbacks, thread-local VFS.
sema-readerLexer and S-Expression reader. Handles f-strings, short lambdas, and regex literals.
sema-vmBytecode compiler and stack VM — the sole evaluator. Lowerer, optimizers, stack resolution, inline cache.
sema-evalInterpreter driver: VM-native macro expansion, module load/import system, prelude, eval/call callback wiring.
sema-stdlibNative stdlib functions (450+ total), higher-order dispatch loops.
sema-llmModel traits, Anthropic/OpenAI/Gemini/Ollama clients, pricing database, local fallback.
sema-lspLSP Language Server (tower-lsp). Completions, definitions, hover metadata.
sema-dapDebug Adapter Protocol server. Frame inspector, stepped walk, breakpoint registry.
sema-fmtCustom code formatter and formatter CLI.
sema-notebookJupyter-inspired notebook: .sema-nb format, shared-env evaluation engine, HTTP server, embedded UI.
sema-docsCanonical structured docs for builtins/special forms; generates the JSON index used by the LSP and REPL.
sema-mcpModel Context Protocol server exposing Sema evaluation and tooling to agents.
sema-wasmWasm bindings for parsing and running Sema code inside the client playground.
semaMain CLI entrypoint. Invokes lsp, dap, REPL, run file, compile bytecode.
10

Visual Architecture Rules

Governing guidelines for constructing extensions to documentation, playground components, or editor integrations.

1. No Drop Shadows

Represent visual depth entirely through color values. Higher levels use lighter warm-neutrals (e.g. #181512), while background canvas layers use deeper tones (e.g. #131110).

2. Rigid Font Boundaries

Monospace text (JetBrains Mono) is strictly reserved for executable s-expressions, code outputs, inline code tags, and technical labels. All descriptive prose must use Inter.

3. Gold is an Accent, Not a Paint

The primary gold (#c8a855) is reserved for highlighting primary active elements, selected menu items, cursor lines, and primary call-to-action buttons. Never scatter decorative gold borders.

4. Single-Pixel Borders

Default borders must be exactly 1px solid with color #2b2620. Focus boundaries and active editor highlights use 2px or 3px solid gold.

11

OpenGraph Social Cards

The actual social preview cards, generated at 1200×630px from og-template.html by scripts/generate-og.mjs and shown here as the live images — homepage hero plus a per-page documentation variant (section category, version badge, page title, description). Regenerate with make site-og.

A. Homepage Preview (1200×630)

Sema homepage OpenGraph card

B. Documentation / Reference Page Preview (1200×630)

Documentation OpenGraph card — stdlib / http-json