# Green Design System - MCP Instructions

Welcome to the GDS MCP! Below are essential instructions to follow when creating code for apps using GDS components. You should also query the MCP to find out which tools and resources are available. Avoid assuming tool and resource names!

## Component Architecture

- All components use `gds-` prefix
- Web components built with Lit (framework-agnostic)
- Angular wrappers: `@sebgroup/green-core-ng` with `Component` suffix
- React wrappers: `@sebgroup/green-core/react` as PascalCase names

## Critical rules to follow

- **Read component-specific instructions.md when available**
- **NEVER guess or assume component API. ALWAYS look up properties in the API docs**
- **Verify full context understanding before writing code**
- **Ask user for clarification if ANY requirement is unclear**
- **ALWAYS read the declarative layout guide ("declarative-layout") before creating any layout**
- **For new apps, ALWAYS read the setup guide for the used framework (Angular or React)**

### Design Tokens

- **REQUIRED**: Use the `get_tokens` tool to look up valid token names before setting style expression properties
- Token categories: `space`, `typography`, `color`, `radius`, `viewport`, `shadow`, `motion`
- Color tokens have subcategories: `background`, `border`, `content`, `state`
- Style expression properties on components (like `padding`, `gap`, `background`, `color`) accept token short names (e.g. `m`, `l`, `xs`) — use `get_tokens` with the appropriate category to discover available names and their resolved values
- Tokens can also be used directly as CSS variables with the `--gds-sys-` prefix (e.g. `var(--gds-sys-space-m)`)

### Typography Rules

- **REQUIRED**: Use `gds-text` component for all headings and paragraphs. But never use inside buttons.
- **REQUIRED**: Use `gds-rich-text` for large bodies of text with varied formatting
- **AVOID**: Direct HTML text elements (h1-h6, p, span), as these will be unstyled
- **DEFAULT STYLES**: `gds-text` headings (h1-h6) and body text (p) already have correct font size, line height, and weight applied via design tokens. Do not add manual `font` or `font-weight` unless deliberately overriding the default visual hierarchy.
- **OVERRIDES**: When visual hierarchy needs differ from the semantic heading level, use the `font` property with a typography token (look up with `get_tokens category=typography`). Only use `font-weight` as a last resort.

### Layout Rules

- **REQUIRED**: Use declarative layout system for all layouts
- **REQUIRED**: Read declarative layout guide ("declarative-layout") before implementing any layout
- **REQUIRED**: Look up property names in API for each declarative layout component
- **PREFERRED**: Declarative layout over custom CSS
- **FORBIDDEN**: Custom CSS for layout unless declarative system cannot support the requirement

### Component Usage Protocol

1. **Verify component capabilities**:
   - Check if component accepts children (has slots)
   - Review properties, events, methods in api.md
   - Check subcomponents field for required relationships

2. **Check constraints**:
   - Verify component relationships (e.g., radio must be in radio-group)
   - Read component instructions.md if exists
   - Review guidelines.md for UX patterns

3. **Framework patterns**:
   - Check framework instructions for each component.