docs: add styles field to MCP Apps specification

- Add styles field to HostContext interface with reference to Theming section
- Add Theming section documenting 36 standardized CSS variables
- Document Host/App behavior for theming including light-dark() usage
- Add Design Decision #4 explaining CSS variables approach
- Include JSON example showing light-dark() pattern

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: 2 people

specification/draft/apps.mdx

@@ -404,6 +404,8 @@ interface HostContext {
   };
   /** Current color theme preference */
   theme?: "light" | "dark";
+  /** CSS variables for theming. See Theming section for standardized variable names. */
+  styles?: Record<string, string>;
   /** How the UI is currently displayed */
   displayMode?: "inline" | "fullscreen" | "pip";
   /** Display modes the host supports */
@@ -440,6 +442,8 @@ interface HostContext {
 
 All fields are optional. Hosts SHOULD provide relevant context. Guest UIs SHOULD handle missing fields gracefully.
 
+For `styles`, apps SHOULD provide CSS fallback values (e.g., `var(--color-text-primary, #171717)`) to handle hosts that don't supply styles.
+
 Example:
 
 ```json
@@ -453,13 +457,64 @@ Example:
     "hostInfo": { "name": "claude-desktop", "version": "1.0.0" },
     "hostContext": {
       "theme": "dark",
+      "styles": {
+        "--color-background-primary": "light-dark(#ffffff, #171717)",
+        "--color-text-primary": "light-dark(#171717, #fafafa)",
+        "--font-family-sans": "system-ui, sans-serif"
+      },
       "displayMode": "inline",
       "viewport": { "width": 400, "height": 300 }
     }
   }
 }
 ```
 
+### Theming
+
+Hosts pass CSS custom properties via `HostContext.styles` for visual cohesion with the host environment.
+
+#### Standardized Variables
+
+| Category | Variables |
+|----------|-----------|
+| Background | `--color-background-primary`, `--color-background-secondary`, `--color-background-tertiary`, `--color-background-inverted` |
+| Text | `--color-text-primary`, `--color-text-secondary`, `--color-text-tertiary`, `--color-text-inverted` |
+| Icons | `--color-icon-primary`, `--color-icon-secondary`, `--color-icon-tertiary`, `--color-icon-inverted` |
+| Borders | `--color-border-primary`, `--color-border-secondary` |
+| Accents | `--color-accent-info`, `--color-accent-danger`, `--color-accent-success`, `--color-accent-warning` |
+| Font Family | `--font-family-sans` |
+| Font Sizes | `--font-size-heading`, `--font-size-body`, `--font-size-caption` |
+| Font Weights | `--font-weight-regular`, `--font-weight-emphasized` |
+| Line Heights | `--font-leading-regular`, `--font-leading-tight` |
+| Composite Styles | `--font-style-heading`, `--font-style-body`, `--font-style-body-emphasized`, `--font-style-caption`, `--font-style-caption-emphasized` |
+| Border Radius | `--border-radius-small`, `--border-radius-medium`, `--border-radius-large`, `--border-radius-full` |
+| Border Width | `--border-width-regular` |
+
+#### Host Behavior
+
+- Hosts MAY provide any subset of standardized variables
+- Hosts MAY use CSS `light-dark()` function for theme-aware values
+- `theme` indicates the active mode; `styles` provides the concrete CSS values
+
+#### App Behavior
+
+- Apps SHOULD use fallback values for CSS variables: `var(--color-text-primary, #171717)`
+- This ensures graceful degradation when hosts omit `styles` or specific variables
+- When the host uses `light-dark()` values, apps MUST set `color-scheme` on their document:
+  ```css
+  :root { color-scheme: light dark; }
+  ```
+
+Example CSS:
+
+```css
+.container {
+  background: var(--color-background-primary, #ffffff);
+  color: var(--color-text-primary, #171717);
+  font: var(--font-style-body, 400 16px/1.4 system-ui);
+}
+```
+
 ### MCP Apps Specific Messages
 
 MCP Apps introduces additional JSON-RPC methods for UI-specific functionality:
@@ -1050,6 +1105,24 @@ This proposal synthesizes feedback from the UI CWG and MCP-UI community, host im
 - **Include external URLs in MVP:** This is one of the easiest content types for servers to adopt, as it's possible to embed regular apps. However, it was deferred due to concerns around model visibility, inability to screenshot content, and review process.
 - **Support multiple content types:** Deferred to maintain a lean MVP.
 
+#### 4. Host Theming via CSS Variables
+
+**Decision:** Provide a standardized set of CSS custom properties for visual cohesion.
+
+**Rationale:**
+
+- CSS variables are universal, framework-agnostic, and require no runtime
+- Apps apply styles via `var(--name)` with fallbacks for graceful degradation
+- Limited variable set (colors, typography, borders) ensures hosts can realistically provide all values
+- Spacing intentionally excluded—layouts break when spacing varies from original design
+- No UI component library—no single library works across all host environments
+
+**Alternatives considered:**
+
+- **Full design system:** Rejected as too prescriptive; hosts have different aesthetics
+- **Inline styles in tool results:** Rejected; separating theming from data enables caching and updates
+- **CSS-in-JS injection:** Rejected; framework-specific and security concerns with injected code
+
 ### Backward Compatibility
 
 The proposal builds on the existing core protocol. There are no incompatibilities.