--- a/visual-spec.md
+++ b/visual-spec.md
@@ -1,70 +1,123 @@
-# Visual Specification — Mastra 1.0 Launch Diagram
+# Visual specification — Mastra 1.0 launch diagram
 
-**Author:** Alex  
-**Last updated:** 2026-04-08  
-**Status:** Draft — pending brand review
+**Author:** Alex
+**Last updated:** 2026-04-13
+**Status:** Updated — aligned to Mastra brand guidelines
 
-## Color Palette Used
+## Color palette
 
-### Primary Colors
-| Role           | Value       | Usage                          |
-|----------------|-------------|--------------------------------|
-| Agent layer    | `#1a73e8`   | Google Blue — main accent      |
-| Memory system  | `#ea4335`   | Google Red — secondary accent  |
-| Workflow engine | `#fbbc04`  | Google Yellow — tertiary       |
-| Tools layer    | `#34a853`   | Google Green — quaternary      |
-| Deployment     | `#9334e6`   | Google Purple — fifth accent   |
+### Light mode
 
-### Background & Surface
-| Role            | Value       |
-|-----------------|-------------|
-| Background      | `#ffffff`   |
-| Code block bg   | `#f1f3f4`   |
-| Code block border | `#dadce0` |
+#### Component fills (monochromatic green scale)
+| Role            | Value       | Mastra token            |
+|-----------------|-------------|-------------------------|
+| Agent layer     | `#085314`   | Primary Green Darkest   |
+| Memory system   | `#0b6e1b`   | Primary Green Dark      |
+| Workflow engine  | `#0d8020`  | Primary Green Primary   |
+| Tools layer     | `#198128`   | Primary Green Lighter   |
+| Deployment      | `#1f9d2f`   | Primary Green Lightest  |
 
-### Text Colors
-| Role           | Value       |
-|----------------|-------------|
-| Title          | `#1a73e8`   |
-| Subtitle       | `#5f6368`   |
-| Body text      | `#202124`   |
-| Connector labels | `#5f6368` |
+#### Background & surface
+| Role              | Value       | Mastra token       |
+|-------------------|-------------|---------------------|
+| Background        | `#fafafa`   | Background          |
+| Code block bg     | `#ededed`   | Surface 3           |
+| Code block border | `#b8b8b8`   | Border Code         |
 
-## Typography Used
+#### Text colors
+| Role             | Value       | Mastra token      |
+|------------------|-------------|---------------------|
+| Title            | `#0a0a0a`   | Text Primary        |
+| Subtitle         | `#5f5f5f`   | Text Tertiary       |
+| Body text        | `#141414`   | Text Secondary      |
+| Connector labels | `#7f7e7e`   | Text Quaternary     |
+| Box labels       | `#ffffff`   | (white on dark bg)  |
+| Box details      | `#84d291`   | Green Muted         |
 
-### Font Stack
-| Role         | Font Family                                |
-|--------------|--------------------------------------------|
-| All text     | Arial, Helvetica, sans-serif               |
-| Code blocks  | "Courier New", Courier, monospace          |
+#### Syntax highlighting (code block)
+| Role     | Value       | Mastra token |
+|----------|-------------|--------------|
+| String   | `#158d29`   | String       |
+| Keyword  | `#d81717`   | Keyword      |
+| Function | `#9829c7`   | Function     |
+| Comment  | `#939393`   | Comment      |
+| Variable | `#0a0a0a`   | Variable     |
 
-### Font Sizes
-| Element        | Size   | Weight |
-|----------------|--------|--------|
-| Title (H1)     | 28px   | Bold   |
-| Subtitle       | 14px   | Normal |
-| Box labels     | 13px   | 600    |
-| Box details    | 11px   | Normal |
-| Code text      | 11px   | 400    |
-| Connector text | 10px   | Normal |
+### Dark mode
 
-### Heading Style
-- Title case used throughout (e.g., "Mastra Architecture Overview", "AGENT LAYER")
+#### Component fills (monochromatic green scale)
+| Role            | Value                       | Mastra token            |
+|-----------------|-----------------------------|-------------------------|
+| Agent layer     | `#16c858`                   | Primary Green Darkest   |
+| Memory system   | `#1fea6a`                   | Primary Green Darker    |
+| Workflow engine  | `hsl(143, 97%, 54%)`       | Primary Green Primary   |
+| Tools layer     | `#62f69d`                   | Primary Green Light     |
+| Deployment      | `#a1fac7`                   | Primary Green Lightest  |
+
+#### Background & surface
+| Role              | Value                    | Mastra token       |
+|-------------------|--------------------------|---------------------|
+| Background        | `#050505`                | Background          |
+| Code block bg     | `#171717`                | Code Background     |
+| Code block border | `hsla(0, 0%, 26%, 1)`   | Border Code         |
+
+#### Text colors
+| Role             | Value       | Mastra token      |
+|------------------|-------------|---------------------|
+| Title            | `#ffffff`   | Text Primary        |
+| Subtitle         | `#939393`   | Text Tertiary       |
+| Body text        | `#e6e6e6`   | Text Secondary      |
+| Connector labels | `#707070`   | Text Quaternary     |
+| Box labels       | `#050505`   | (dark on light bg)  |
+| Box details      | `#050505`   | Background          |
+
+#### Syntax highlighting (code block)
+| Role     | Value       | Mastra token |
+|----------|-------------|--------------|
+| String   | `#46f488`   | String       |
+| Keyword  | `#fa7b6a`   | Keyword      |
+| Function | `#d06bee`   | Function     |
+| Comment  | `#939393`   | Comment      |
+| Variable | `#fff`      | Variable     |
+
+## Typography
+
+### Font stack
+| Role        | Font family                                                                                                                              |
+|-------------|------------------------------------------------------------------------------------------------------------------------------------------|
+| All text    | "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto", "Oxygen", "Ubuntu", "Cantarell", "Fira Sans", "Droid Sans", "Helvetica Neue", sans-serif |
+| Code blocks | "Geist Mono", "Menlo", "Monaco", "Courier New", monospace                                                                               |
+
+### Font sizes
+| Element          | Size     | Weight | Notes                     |
+|------------------|----------|--------|---------------------------|
+| Title (H1)       | 2.25rem  | Bold   | 36px, letter-spacing -0.028em |
+| Subtitle         | 1rem     | Normal | 16px base                 |
+| Box labels       | 0.875rem | 600    | 14px                      |
+| Box details      | 0.875rem | Normal | 14px                      |
+| Code text        | 0.875rem | 500    | 14px, monospace           |
+| Connector text   | 0.875rem | Normal | 14px                      |
+
+### Heading style
+- Sentence case throughout (e.g., "Mastra architecture overview", "Agent layer")
+- H2 and H3 elements include a bottom border
+- Line height: 1.6 for body text
 
 ## Layout
 
-- Canvas: 800x500px, white background, 8px border radius
+- Canvas: 800x500px, `#fafafa` background (light) / `#050505` (dark), 8px border radius
 - Component boxes: 200x110px (top row), 200x100px (bottom row), 8px radius
 - Code example block: 600x90px at bottom
-- Connector arrows: 2px stroke, #5f6368, with arrowhead markers
+- Connector arrows: 2px stroke, text-quaternary color, with arrowhead markers
+- Borders on all surfaces: `#ccc` (light) / `#343434` (dark)
 
-## Known Issues (From Brand Review)
+## Resolved issues (from prior brand review)
 
-1. **Colors are wrong** — Uses Google Material palette instead of Mastra brand greens
-2. **Fonts are wrong** — Uses Arial instead of Inter; uses Courier New instead of Geist Mono
-3. **Title color is blue** — Should use Mastra primary text color
-4. **Background is pure white** — Should use Mastra background (#fafafa light mode)
-5. **Heading style is title case** — Mastra uses sentence case
-6. **Subtitle contains marketing language** — "How the Powerful Agent Framework Works"
-7. **Code block styling** — Background and border don't match Mastra surface/border tokens
-8. **No dark mode variant** — Brand requires both light and dark mode specs
+1. ~~Colors are wrong~~ — Replaced Google Material palette with Mastra green scale
+2. ~~Fonts are wrong~~ — Switched to Inter / Geist Mono
+3. ~~Title color is blue~~ — Now uses text-primary (`#0a0a0a` light / `#ffffff` dark)
+4. ~~Background is pure white~~ — Now uses Mastra background token (`#fafafa` / `#050505`)
+5. ~~Heading style is title case~~ — Switched to sentence case
+6. ~~Subtitle contains marketing language~~ — Changed to "TypeScript agent framework architecture"
+7. ~~Code block styling~~ — Uses Mastra surface-3 / border-code tokens
+8. ~~No dark mode variant~~ — Full dark mode spec added