@jamesodwyer/gds-figma-vite 2.0.2 → 2.0.4

package/guidelines/Guidelines.md

@@ -74,10 +74,123 @@ function App() {
 
 ---
 
+## CRITICAL: Compound Component Pattern
+
+Many GDS components use the **compound component pattern**. Sub-components are accessed via dot notation on the parent component, NOT as separate imports.
+
+### Correct Usage (Dot Notation)
+
+```tsx
+// ✅ CORRECT - Use dot notation for sub-components
+<Modal>
+  <Modal.Header>...</Modal.Header>
+  <Modal.Title>...</Modal.Title>
+  <Modal.Content>...</Modal.Content>
+  <Modal.Description>...</Modal.Description>
+  <Modal.Actions>...</Modal.Actions>
+</Modal>
+
+<Card>
+  <Card.Title>...</Card.Title>
+  <Card.Body>...</Card.Body>
+</Card>
+
+<InputField id="email">
+  <InputField.Label>...</InputField.Label>
+  <InputField.Input />
+</InputField>
+```
+
+### WRONG Usage (Do NOT Do This)
+
+```tsx
+// ❌ WRONG - These components DO NOT EXIST as separate imports
+<ModalHeader>      // WRONG - use Modal.Header
+<ModalTitle>       // WRONG - use Modal.Title
+<ModalContent>     // WRONG - use Modal.Content
+<ModalDescription> // WRONG - use Modal.Description
+<ModalActions>     // WRONG - use Modal.Actions
+<CardTitle>        // WRONG - use Card.Title
+<CardBody>         // WRONG - use Card.Body
+<CardContent>      // WRONG - does not exist at all
+```
+
+### Components with Compound Sub-components
+
+| Component | Sub-components |
+|-----------|----------------|
+| Modal | `.Header`, `.Title`, `.Content`, `.Description`, `.Image`, `.CloseButton`, `.Actions` |
+| Card | `.Title`, `.Body` |
+| InputField | `.Label`, `.Row`, `.Input`, `.Textarea`, `.Select`, `.Checkbox`, `.Radio`, `.StartIcon`, `.EndIcon`, `.Validation` |
+| Accordion | `.Item`, `.Toggle`, `.Content` |
+
+---
+
+## CRITICAL: Non-Existent Components
+
+> **⚠️ WARNING FOR AI AGENTS**: The following components DO NOT exist in this design system. Do NOT generate code using them.
+
+### Components That DO NOT Exist
+
+| Non-Existent | Use Instead |
+|--------------|-------------|
+| `ButtonGroup` | Use `Stack` with `gap` prop, or a styled `div` with flexbox |
+| `CardContent` | Put content directly inside `Card.Body` |
+| `CardHeader` | Use `Card.Title` |
+| `CardActions` | Put buttons inside `Card.Body` |
+| `ModalDescription` | Use `Modal.Description` (compound component) |
+| `ModalHeader` | Use `Modal.Header` (compound component) |
+| `ModalBody` | Use `Modal.Content` (compound component) |
+| `ModalFooter` | Use `Modal.Actions` (compound component) |
+| `FormControl` | Use `InputField` compound component |
+| `FormLabel` | Use `InputField.Label` |
+| `FormHelperText` | Use `InputField.Validation` |
+| `Grid` | Use CSS Grid or styled `div` |
+| `Box` | Use styled `div` with spacing tokens |
+| `Container` | Use styled `div` with spacing tokens |
+| `Typography` | Use `TextStyle` component |
+| `Divider` | Use styled `hr` or `div` |
+| `IconButton` | Use `CircleButton` or `SquareButton` |
+| `Snackbar` | Use `Toast` |
+| `Dialog` | Use `Modal` |
+| `Drawer` | Use `SidePanel` |
+| `AppBar` | Use `Header` |
+
+### Layout Without ButtonGroup
+
+Use `Stack` for horizontal button layouts:
+
+```tsx
+import { Stack, Button } from '@jamesodwyer/gds-figma-vite';
+
+// For horizontal button group
+<Stack gap="club" style={{ display: 'flex', flexDirection: 'row' }}>
+  <Button colorVariant="secondary">Cancel</Button>
+  <Button colorVariant="primary">Confirm</Button>
+</Stack>
+
+// Or use a styled div
+import styled from 'styled-components';
+import { spacing } from '@jamesodwyer/gds-figma-vite';
+
+const ButtonRow = styled.div`
+  display: flex;
+  gap: ${spacing.club};
+`;
+
+<ButtonRow>
+  <Button colorVariant="secondary">Cancel</Button>
+  <Button colorVariant="primary">Confirm</Button>
+</ButtonRow>
+```
+
+---
+
 ## IMPORTANT: Code Generation Rules
 
 ### DO:
 - Always wrap with `GdsProvider` or `ThemeProvider`
+- Use compound component syntax (`Modal.Header`, `Card.Body`, etc.)
 - Use semantic color tokens from theme (`theme.base.primary`, `theme.status.danger`)
 - Use spacing tokens (`spacing.auditorium`, `spacing.arena`)
 - Use textStyle for typography (`textStyle.rainier`, `textStyle.everest`)
@@ -86,6 +199,8 @@ function App() {
 - Import components from `@jamesodwyer/gds-figma-vite`
 
 ### DO NOT:
+- **Never import sub-components separately** - use dot notation (`Modal.Header` not `ModalHeader`)
+- **Never use components that don't exist** - check the exports list above
 - Never hardcode hex color values - always use theme tokens
 - Never use pixel values for spacing - use spacing tokens
 - Never use custom font sizes - use textStyle utilities
@@ -116,6 +231,7 @@ function App() {
 ### Layout Components
 | Component | Purpose | Docs |
 |-----------|---------|------|
+| `Stack` | Spacing utility for vertical/horizontal layouts | [Stack.md](./components/Stack.md) |
 | `Card` | Content containers with Title and Body | [Card.md](./components/Card.md) |
 | `Modal` | Overlay dialogs requiring user attention | [Modal.md](./components/Modal.md) |
 | `SidePanel` | Slide-in panels for supplementary content | [SidePanel.md](./components/SidePanel.md) |

package/guidelines/components/Card.md

@@ -8,6 +8,8 @@ Container component for grouping related content with optional elevation and sty
 import { Card } from '@jamesodwyer/gds-figma-vite';
 ```
 
+> **⚠️ IMPORTANT**: Card uses a compound component pattern. Sub-components are accessed via dot notation (`Card.Title`, `Card.Body`), NOT as separate imports.
+
 ## Purpose
 
 Use Card to:
@@ -15,13 +17,60 @@ Use Card to:
 - Create visual separation between content areas
 - Display information in a contained, elevated surface
 
-## Structure
+## Structure (Compound Components)
+
+Card uses **dot notation** for sub-components. These are NOT separate imports.
 
 | Sub-component | Description |
 |---------------|-------------|
-| Card | Main container |
-| Card.Title | Header/title area |
-| Card.Body | Main content area |
+| `Card` | Main container |
+| `Card.Title` | Header/title area |
+| `Card.Body` | Main content area |
+
+### ❌ WRONG - Do Not Use These (They Don't Exist)
+
+```tsx
+// These components DO NOT EXIST - do not import or use them:
+<CardTitle>    // ❌ WRONG
+<CardBody>     // ❌ WRONG
+<CardContent>  // ❌ WRONG - does not exist at all
+<CardHeader>   // ❌ WRONG
+<CardActions>  // ❌ WRONG
+<CardFooter>   // ❌ WRONG
+```
+
+### ✅ CORRECT - Use Dot Notation
+
+```tsx
+// Always use dot notation:
+<Card>
+  <Card.Title>My Title</Card.Title>    // ✅ CORRECT
+  <Card.Body>My content</Card.Body>    // ✅ CORRECT
+</Card>
+```
+
+### Note on CardContent
+
+There is **NO `CardContent` component**. Put your content directly inside `Card.Body`:
+
+```tsx
+// ❌ WRONG - CardContent doesn't exist
+<Card>
+  <Card.Body>
+    <CardContent>  {/* This will cause an error! */}
+      <p>Content</p>
+    </CardContent>
+  </Card.Body>
+</Card>
+
+// ✅ CORRECT - Put content directly in Card.Body
+<Card>
+  <Card.Body>
+    <TextStyle>Content goes here</TextStyle>
+    <Button>Action</Button>
+  </Card.Body>
+</Card>
+```
 
 ## Basic Usage
 

package/guidelines/components/Modal.md

@@ -8,6 +8,8 @@ Overlay dialog for focused user interactions requiring attention or action.
 import { Modal } from '@jamesodwyer/gds-figma-vite';
 ```
 
+> **⚠️ IMPORTANT**: Modal uses a compound component pattern. All sub-components are accessed via dot notation (`Modal.Header`, `Modal.Title`, etc.), NOT as separate imports.
+
 ## Purpose
 
 Use Modal for:
@@ -16,18 +18,44 @@ Use Modal for:
 - Important information that needs acknowledgment
 - Alert dialogs
 
-## Structure
+## Structure (Compound Components)
+
+Modal uses **dot notation** for sub-components. These are NOT separate imports.
 
 | Sub-component | Description |
 |---------------|-------------|
-| Modal | Container with backdrop |
-| Modal.Header | Header section |
-| Modal.Title | Modal title |
-| Modal.Content | Main content area |
-| Modal.Description | Descriptive text |
-| Modal.Image | Optional banner image |
-| Modal.CloseButton | Close button |
-| Modal.Actions | Action buttons container |
+| `Modal` | Container with backdrop |
+| `Modal.Header` | Header section |
+| `Modal.Title` | Modal title |
+| `Modal.Content` | Main content area |
+| `Modal.Description` | Descriptive text |
+| `Modal.Image` | Optional banner image |
+| `Modal.CloseButton` | Close button |
+| `Modal.Actions` | Action buttons container |
+
+### ❌ WRONG - Do Not Use These (They Don't Exist)
+
+```tsx
+// These components DO NOT EXIST - do not import or use them:
+<ModalHeader>       // ❌ WRONG
+<ModalTitle>        // ❌ WRONG
+<ModalContent>      // ❌ WRONG
+<ModalDescription>  // ❌ WRONG
+<ModalActions>      // ❌ WRONG
+<ModalFooter>       // ❌ WRONG
+<ModalBody>         // ❌ WRONG
+```
+
+### ✅ CORRECT - Use Dot Notation
+
+```tsx
+// Always use dot notation:
+<Modal.Header>      // ✅ CORRECT
+<Modal.Title>       // ✅ CORRECT
+<Modal.Content>     // ✅ CORRECT
+<Modal.Description> // ✅ CORRECT
+<Modal.Actions>     // ✅ CORRECT
+```
 
 ## Props
 

package/guidelines/components/Stack.md

@@ -0,0 +1,174 @@
+# Stack Component
+
+Simple layout utility for adding consistent spacing between child elements.
+
+## Import
+
+```tsx
+import { Stack } from '@jamesodwyer/gds-figma-vite';
+```
+
+## Purpose
+
+Use Stack to:
+- Add consistent vertical spacing between elements
+- Create horizontal layouts with gaps (using CSS)
+- Replace non-existent `ButtonGroup` component
+- Quickly layout form elements or content sections
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| gap | SpacingToken | - | Gap between children using spacing scale |
+
+### Available Gap Values
+
+| Token | Value |
+|-------|-------|
+| `lounge` | 4px |
+| `club` | 8px |
+| `hall` | 12px |
+| `auditorium` | 16px |
+| `theatre` | 20px |
+| `amphitheatre` | 24px |
+| `arena` | 32px |
+| `stadium` | 48px |
+| `dome` | 64px |
+| `field` | 88px |
+
+## Basic Usage (Vertical Stack)
+
+```tsx
+import { GdsProvider, Stack, Button } from '@jamesodwyer/gds-figma-vite';
+
+<GdsProvider>
+  <Stack gap="auditorium">
+    <Button colorVariant="primary">First Button</Button>
+    <Button colorVariant="secondary">Second Button</Button>
+    <Button colorVariant="tertiary">Third Button</Button>
+  </Stack>
+</GdsProvider>
+```
+
+## Horizontal Layout (Button Row)
+
+> **Note**: `ButtonGroup` does not exist in GDS. Use Stack with flex styling instead.
+
+```tsx
+import { GdsProvider, Stack, Button } from '@jamesodwyer/gds-figma-vite';
+
+<GdsProvider>
+  <Stack gap="club" style={{ display: 'flex', flexDirection: 'row' }}>
+    <Button colorVariant="secondary">Cancel</Button>
+    <Button colorVariant="primary">Confirm</Button>
+  </Stack>
+</GdsProvider>
+```
+
+## With Styled Components
+
+For more control, extend Stack with styled-components:
+
+```tsx
+import styled from 'styled-components';
+import { Stack, Button, spacing } from '@jamesodwyer/gds-figma-vite';
+
+const ButtonRow = styled(Stack)`
+  display: flex;
+  flex-direction: row;
+  justify-content: flex-end;
+`;
+
+<ButtonRow gap="club">
+  <Button colorVariant="secondary">Cancel</Button>
+  <Button colorVariant="primary">Submit</Button>
+</ButtonRow>
+```
+
+## Form Layout Example
+
+```tsx
+import { GdsProvider, Stack, InputField, Button } from '@jamesodwyer/gds-figma-vite';
+
+<GdsProvider>
+  <form>
+    <Stack gap="auditorium">
+      <InputField id="name">
+        <InputField.Label>Name</InputField.Label>
+        <InputField.Row marginTop="club">
+          <InputField.Input />
+        </InputField.Row>
+      </InputField>
+
+      <InputField id="email">
+        <InputField.Label>Email</InputField.Label>
+        <InputField.Row marginTop="club">
+          <InputField.Input type="email" />
+        </InputField.Row>
+      </InputField>
+
+      <Button colorVariant="primary" fullWidth>
+        Submit
+      </Button>
+    </Stack>
+  </form>
+</GdsProvider>
+```
+
+## Alternative: Styled Div
+
+If you prefer more explicit control, use a styled div:
+
+```tsx
+import styled from 'styled-components';
+import { spacing } from '@jamesodwyer/gds-figma-vite';
+
+const VerticalStack = styled.div`
+  display: flex;
+  flex-direction: column;
+  gap: ${spacing.auditorium};
+`;
+
+const HorizontalStack = styled.div`
+  display: flex;
+  flex-direction: row;
+  gap: ${spacing.club};
+`;
+```
+
+## Common Patterns
+
+### Modal Actions (Replacing ButtonGroup)
+
+```tsx
+<Modal.Actions>
+  <Stack gap="club" style={{ display: 'flex', flexDirection: 'row', justifyContent: 'flex-end' }}>
+    <Button colorVariant="secondary" onClick={handleCancel}>
+      Cancel
+    </Button>
+    <Button colorVariant="primary" onClick={handleConfirm}>
+      Confirm
+    </Button>
+  </Stack>
+</Modal.Actions>
+```
+
+### Card Content Layout
+
+```tsx
+<Card>
+  <Card.Body>
+    <Stack gap="auditorium">
+      <TextStyle>First section of content</TextStyle>
+      <TextStyle>Second section of content</TextStyle>
+      <Button colorVariant="primary">Action</Button>
+    </Stack>
+  </Card.Body>
+</Card>
+```
+
+## Related Components
+
+- `Modal.Actions` - Container for modal action buttons
+- `InputField.Row` - Row container with margin support for form inputs

package/guidelines/guidelines-template.md

@@ -0,0 +1,385 @@
+# Ticketmaster Global Design System (GDS) - AI Guidelines
+
+> **FOR AI AGENTS**: This is a self-contained guide for code generation. All information is in this single file.
+
+## Package Information
+
+- **Package**: `@jamesodwyer/gds-figma-vite`
+- **Framework**: React 18+ with styled-components
+- **Themes**: TM (Ticketmaster/blue), LN (Live Nation/red)
+
+---
+
+## REQUIRED: GdsProvider Wrapper
+
+Every application MUST wrap components with `GdsProvider`:
+
+```tsx
+import { GdsProvider, Button } from '@jamesodwyer/gds-figma-vite';
+
+function App() {
+  return (
+    <GdsProvider theme="TM">
+      <Button colorVariant="primary">Click Me</Button>
+    </GdsProvider>
+  );
+}
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| theme | 'TM' \| 'LN' | 'TM' | Brand theme |
+| includeGlobalStyles | boolean | true | Include global CSS |
+
+---
+
+## CRITICAL: Compound Component Pattern
+
+Many GDS components use **dot notation** for sub-components. These are NOT separate imports.
+
+### Correct Usage
+
+```tsx
+// CORRECT - Use dot notation
+<Modal>
+  <Modal.Header>
+    <Modal.Title>Title</Modal.Title>
+    <Modal.CloseButton label="Close" />
+  </Modal.Header>
+  <Modal.Content>
+    <Modal.Description>Content here</Modal.Description>
+  </Modal.Content>
+  <Modal.Actions>
+    <Button colorVariant="secondary">Cancel</Button>
+    <Button colorVariant="primary">Confirm</Button>
+  </Modal.Actions>
+</Modal>
+
+<Card>
+  <Card.Title>Card Title</Card.Title>
+  <Card.Body>Card content</Card.Body>
+</Card>
+
+<InputField id="email">
+  <InputField.Label>Email</InputField.Label>
+  <InputField.Row marginTop="club">
+    <InputField.Input type="email" />
+  </InputField.Row>
+</InputField>
+```
+
+### Components with Sub-components
+
+| Component | Sub-components (use dot notation) |
+|-----------|-----------------------------------|
+| `Modal` | `.Header`, `.Title`, `.Content`, `.Description`, `.Image`, `.CloseButton`, `.Actions` |
+| `Card` | `.Title`, `.Body` |
+| `InputField` | `.Label`, `.Row`, `.Input`, `.Textarea`, `.Select`, `.Checkbox`, `.Radio`, `.StartIcon`, `.EndIcon`, `.Validation` |
+| `Accordion` | `.Item`, `.Toggle`, `.Content` |
+
+---
+
+## CRITICAL: Components That DO NOT Exist
+
+> **WARNING**: These components are NOT in GDS. Do NOT use them.
+
+| DO NOT USE | Use Instead |
+|------------|-------------|
+| `ButtonGroup` | `<div style={{display:'flex',gap:'8px'}}>` or styled div |
+| `CardContent` | Put content directly in `Card.Body` |
+| `CardHeader` | Use `Card.Title` |
+| `CardActions` | Put buttons in `Card.Body` |
+| `ModalDescription` | Use `Modal.Description` (dot notation) |
+| `ModalHeader` | Use `Modal.Header` (dot notation) |
+| `ModalBody` | Use `Modal.Content` (dot notation) |
+| `ModalFooter` | Use `Modal.Actions` (dot notation) |
+| `FormControl` | Use `InputField` |
+| `FormLabel` | Use `InputField.Label` |
+| `Grid` | Use CSS Grid or styled div |
+| `Box` | Use styled div |
+| `Container` | Use styled div |
+| `Typography` | Use `TextStyle` |
+| `Divider` | Use styled hr or div |
+| `Snackbar` | Use `Toast` |
+| `Dialog` | Use `Modal` |
+| `Drawer` | Use `SidePanel` |
+
+### Button Row Example (Instead of ButtonGroup)
+
+```tsx
+// For horizontal button layouts:
+<div style={{ display: 'flex', gap: '8px' }}>
+  <Button colorVariant="secondary">Cancel</Button>
+  <Button colorVariant="primary">Confirm</Button>
+</div>
+```
+
+---
+
+## Available Components
+
+### Layout
+- `Card` - Container with `.Title`, `.Body`
+- `Modal` - Dialog with `.Header`, `.Title`, `.Content`, `.Description`, `.CloseButton`, `.Actions`
+- `SidePanel` - Slide-in panel
+- `Accordion` - Collapsible sections
+- `Header` - Page header
+- `Footer` - Page footer
+
+### Buttons
+- `Button` - Primary button (colorVariant: 'primary' | 'secondary' | 'tertiary')
+- `CircleButton` - Circular icon button
+- `SquareButton` - Square icon button
+- `PillButton` - Pill-shaped button
+
+### Form Inputs
+- `InputField` - Compound form input (see sub-components above)
+- `TextInput` - Simple text input
+- `TextArea` - Multi-line input
+- `Checkbox` - Boolean selection
+- `RadioButton` - Single selection
+- `SelectInput` - Dropdown
+- `ToggleSwitch` - On/off switch
+- `PasswordInput` - Password with toggle
+- `PhoneNumber` - Phone with country code
+- `DateOfBirth` - Date input
+- `CountryPicker` - Country dropdown
+- `Stepper` - Increment/decrement
+
+### Feedback
+- `Toast` - Temporary notification
+- `AlertBox` - Inline alert (status: 'info' | 'success' | 'warning' | 'danger')
+- `LoadingSpinner` - Loading indicator
+- `Skeleton` - Loading placeholder
+- `ErrorMessage` - Error text
+- `SuccessMessage` - Success text
+- `Badge` - Status label
+- `Tooltip` - Hover tooltip
+
+### Typography
+- `TextStyle` - Styled text spans
+- `TitleHeading` - Page titles
+- `DisplayHeading` - Hero text
+- `Link` - Styled links
+
+---
+
+## Spacing Tokens
+
+Use spacing tokens instead of pixel values:
+
+```tsx
+import { spacing } from '@jamesodwyer/gds-figma-vite';
+```
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| `spacing.lounge` | 4px | Tight spacing, icon gaps |
+| `spacing.club` | 8px | Small gaps |
+| `spacing.hall` | 12px | Small padding |
+| `spacing.auditorium` | 16px | Default padding |
+| `spacing.theatre` | 20px | Medium spacing |
+| `spacing.amphitheatre` | 24px | Large padding |
+| `spacing.arena` | 32px | Section spacing |
+| `spacing.stadium` | 48px | Large sections |
+| `spacing.dome` | 64px | Page sections |
+| `spacing.field` | 88px | Hero spacing |
+
+```tsx
+import styled from 'styled-components';
+import { spacing } from '@jamesodwyer/gds-figma-vite';
+
+const Container = styled.div`
+  padding: ${spacing.auditorium};
+  gap: ${spacing.club};
+  margin-bottom: ${spacing.arena};
+`;
+```
+
+---
+
+## Typography (textStyle)
+
+Use `textStyle` for consistent typography:
+
+```tsx
+import { textStyle } from '@jamesodwyer/gds-figma-vite';
+```
+
+| Style | Size | Weight | Usage |
+|-------|------|--------|-------|
+| `textStyle.mauna` | 44-54px | 700 | Hero displays |
+| `textStyle.everest` | 32-44px | 700 | Page titles |
+| `textStyle.kilimanjaro` | 24-32px | 700 | Section headers |
+| `textStyle.matterhorn` | 24-28px | 700 | Large headings |
+| `textStyle.vinson` | 22-24px | 700 | Subheadings |
+| `textStyle.blanc` | 18-20px | 700 | Small headers |
+| `textStyle.fiji` | 18px | 600 | Emphasized body |
+| `textStyle.rainier` | 16px | 400 | Body text (default) |
+| `textStyle.etna` | 14px | 400 | Small text |
+| `textStyle.snowdon` | 12px | 600 | Labels/captions |
+
+```tsx
+import styled from 'styled-components';
+import { textStyle } from '@jamesodwyer/gds-figma-vite';
+
+const Title = styled.h1`
+  ${textStyle.everest}
+`;
+
+const Body = styled.p`
+  ${textStyle.rainier}
+`;
+```
+
+---
+
+## Elevation (Shadows)
+
+```tsx
+import { elevation } from '@jamesodwyer/gds-figma-vite';
+```
+
+| Level | Usage |
+|-------|-------|
+| `elevation.level0` | Default (no shadow) |
+| `elevation.level1` | Cards, content blocks |
+| `elevation.level2` | Sticky headers |
+| `elevation.level3` | Multiple sticky elements |
+| `elevation.level4` | Modals, dialogs |
+
+```tsx
+const Card = styled.div`
+  ${elevation.level1}
+  background: white;
+`;
+```
+
+---
+
+## Theme Colors
+
+Access colors through theme props:
+
+```tsx
+const Component = styled.div`
+  background: ${props => props.theme.base.bg};
+  color: ${props => props.theme.text.primary};
+  border-color: ${props => props.theme.base.border};
+
+  &.error { color: ${props => props.theme.status.danger}; }
+  &.success { color: ${props => props.theme.status.success}; }
+`;
+```
+
+### Theme Color Categories
+- `theme.base.primary` - Brand primary color
+- `theme.base.bg` - Background
+- `theme.base.border` - Border color
+- `theme.text.primary` - Primary text
+- `theme.text.secondary` - Secondary text
+- `theme.status.success` - Success green
+- `theme.status.danger` - Error red
+- `theme.status.warning` - Warning yellow
+
+---
+
+## Icons
+
+Import icons directly:
+
+```tsx
+import { HeartIcon, CheckmarkIcon, CloseIcon } from '@jamesodwyer/gds-figma-vite';
+
+// Usage
+<HeartIcon size="24" />
+<Button startIcon={<CheckmarkIcon />}>Confirm</Button>
+```
+
+Icon props: `size` (string like "24" or "1.5rem"), `fillColor` (optional)
+
+---
+
+## Button Props
+
+```tsx
+<Button
+  colorVariant="primary"    // 'primary' | 'secondary' | 'tertiary'
+  fullWidth={false}         // boolean
+  disabled={false}          // boolean
+  startIcon={<Icon />}      // ReactNode
+  endIcon={<Icon />}        // ReactNode
+  onClick={() => {}}        // function
+>
+  Button Text
+</Button>
+```
+
+---
+
+## Modal Props
+
+```tsx
+<Modal
+  isOpen={true}                    // boolean
+  onClose={() => setOpen(false)}   // function (required)
+  ariaLabel="Modal title"          // string (required)
+  mobileMaxViewportWidth="768px"   // string (required)
+  role="dialog"                    // 'dialog' | 'alertdialog'
+  size="standard"                  // 'standard' | 'large'
+  variant="default"                // 'default' | 'danger'
+>
+  <Modal.Header>
+    <Modal.Title>Title</Modal.Title>
+    <Modal.CloseButton label="Close modal" />
+  </Modal.Header>
+  <Modal.Content>
+    <Modal.Description>Content</Modal.Description>
+  </Modal.Content>
+  <Modal.Actions>
+    <Button colorVariant="secondary">Cancel</Button>
+    <Button colorVariant="primary">Confirm</Button>
+  </Modal.Actions>
+</Modal>
+```
+
+---
+
+## InputField Props
+
+```tsx
+<InputField id="fieldId">  {/* id is required */}
+  <InputField.Label>Label Text</InputField.Label>
+  <InputField.Row marginTop="club">
+    <InputField.Input
+      type="text"           // 'text' | 'email' | 'password' | etc.
+      placeholder="..."
+      isErrored={false}     // boolean - shows error styling
+    />
+  </InputField.Row>
+  <InputField.Validation
+    type="error"            // 'error' | 'success'
+    screenReaderErrorPrefix="Error:"
+  >
+    Error message here
+  </InputField.Validation>
+</InputField>
+```
+
+---
+
+## Code Generation Rules
+
+### DO:
+- Wrap with `GdsProvider`
+- Use compound component syntax (`Modal.Header`, `Card.Body`)
+- Use spacing tokens (`spacing.auditorium`)
+- Use textStyle for typography
+- Use theme colors (`props.theme.base.primary`)
+
+### DO NOT:
+- Import sub-components separately (use dot notation)
+- Use components that don't exist (ButtonGroup, CardContent, etc.)
+- Hardcode hex colors
+- Hardcode pixel values for spacing
+- Skip the GdsProvider wrapper

package/guidelines/overview-components.md

@@ -2,6 +2,42 @@
 
 All components are imported from `@jamesodwyer/gds-figma-vite`.
 
+---
+
+## CRITICAL: Compound Component Pattern
+
+Several GDS components use the **compound component pattern**. Sub-components are accessed via **dot notation**, NOT as separate imports.
+
+### Components with Sub-components
+
+| Component | Sub-components (use dot notation) |
+|-----------|-----------------------------------|
+| `Modal` | `.Header`, `.Title`, `.Content`, `.Description`, `.Image`, `.CloseButton`, `.Actions` |
+| `Card` | `.Title`, `.Body` |
+| `InputField` | `.Label`, `.Row`, `.Input`, `.Textarea`, `.Select`, `.Checkbox`, `.Radio`, `.StartIcon`, `.EndIcon`, `.Validation` |
+| `Accordion` | `.Item`, `.Toggle`, `.Content` |
+
+### Example Usage
+
+```tsx
+// ✅ CORRECT - Use dot notation
+<Modal>
+  <Modal.Header>
+    <Modal.Title>Title</Modal.Title>
+  </Modal.Header>
+  <Modal.Content>
+    <Modal.Description>Content</Modal.Description>
+  </Modal.Content>
+</Modal>
+
+// ❌ WRONG - These don't exist as separate components
+<ModalHeader>     // Does not exist
+<ModalContent>    // Does not exist
+<CardContent>     // Does not exist
+```
+
+---
+
 ## Layout Components
 
 | Component | Description | Usage |
@@ -83,10 +119,39 @@ All components are imported from `@jamesodwyer/gds-figma-vite`.
 
 | Component | Description | Usage |
 |-----------|-------------|-------|
+| Stack | Vertical/horizontal layout with spacing | Element spacing, button rows |
 | Countdown | Timer countdown | Time-limited offers |
 | CountdownTimer | Alternative timer | Countdown displays |
 | ShareCard | Social sharing card | Share dialogs |
 | BrandLogo | Brand logo display | Branding |
+| VisuallyHidden | Screen reader only content | Accessibility |
+| IconButton | Icon-only button utility | Icon actions |
+
+---
+
+## Components That DO NOT Exist
+
+> **WARNING**: The following components are NOT part of GDS. Do not use them.
+
+| Non-Existent Component | Use Instead |
+|------------------------|-------------|
+| `ButtonGroup` | `Stack` with flex styling |
+| `CardContent` | Put content in `Card.Body` |
+| `CardHeader` | Use `Card.Title` |
+| `CardActions` | Put buttons in `Card.Body` |
+| `ModalDescription` | Use `Modal.Description` |
+| `ModalHeader` | Use `Modal.Header` |
+| `ModalBody` | Use `Modal.Content` |
+| `ModalFooter` | Use `Modal.Actions` |
+| `FormControl` | Use `InputField` |
+| `Grid` | Use CSS Grid or styled div |
+| `Box` | Use styled div with spacing tokens |
+| `Container` | Use styled div with spacing tokens |
+| `Typography` | Use `TextStyle` |
+| `Divider` | Use styled hr or div |
+| `Snackbar` | Use `Toast` |
+| `Dialog` | Use `Modal` |
+| `Drawer` | Use `SidePanel` |
 
 ## Import Examples
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jamesodwyer/gds-figma-vite",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "publishConfig": {
     "access": "public"
   },