From 0a5567fccc7c8632fcc4ca019d49ff8e8c54ff92 Mon Sep 17 00:00:00 2001
From: damann <67584870+damann@users.noreply.github.com>
Date: Mon, 13 Apr 2026 15:58:57 +0200
Subject: [PATCH 01/13] Create Forma 36 skill documentation

Add Forma 36 skill documentation for UI development using Contentful's design system, including rules, guidelines, and component usage.
---
 skill/forma-36-skill | 874 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 874 insertions(+)
 create mode 100644 skill/forma-36-skill

diff --git a/skill/forma-36-skill b/skill/forma-36-skill
new file mode 100644
index 0000000000..9b4628a783
--- /dev/null
+++ b/skill/forma-36-skill
@@ -0,0 +1,874 @@
+name: forma36
+description: Build UI using Forma 36, Contentful's design system. Use when the user references Forma 36, f36, Contentful components, or wants to build a Contentful app UI — including prototypes, screens, and interface explorations.
+---
+
+# Forma 36 — Contentful Design System
+
+Forma 36 is the design language of Contentful. Every prototype, screen, and component built for Contentful must look and feel like it belongs in the Contentful product. This skill ensures that.
+
+The goal is not to use the right component name — it's to produce UI that is indistinguishable from the real Contentful interface.
+
+## Scope, Authority, and Rule Interpretation
+
+This document is the primary operational specification for generating UI with Forma 36.
+
+Use it to determine:
+- which UI structures are allowed
+- which components and patterns to use
+- which visual and writing rules are mandatory
+- which implementations are forbidden
+
+This is a normative specification. Outputs must follow explicit rules. Philosophy sections explain intent but do not override rules or permit invention.
+
+---
+
+## Rule Types
+
+All guidance is expressed using the following rule types:
+
+- **Required** — mandatory in every applicable case. Treat as pass/fail.
+- **Forbidden** — never allowed. If present, the UI is incorrect.
+- **Preferred** — default choice unless a more specific rule overrides it.
+- **Context-dependent** — mandatory only when the stated condition is true.
+
+### Rule precedence
+
+Apply rules in this order:
+1. Forbidden
+2. Required
+3. Context-dependent (when condition is true)
+4. Preferred
+5. Philosophy and explanatory text
+
+When applying rules:
+- apply conditional rules only when their condition is true
+- when rules conflict, the more specific rule wins
+- Forbidden rules always take precedence
+
+Only explicit rules, named components, defined patterns, and tokenized values are normative.
+
+---
+
+## Supporting Files
+
+Supporting files extend this specification with domain-specific detail.
+
+Apply them as follows:
+- use this document first to determine structure and rule intent
+- use the relevant supporting file for detailed decisions
+- when rules do not conflict, apply both
+- when rules conflict, the more specific rule wins
+
+This skill is split across four reference files. Read the relevant one for the task at hand:
+
+| File | What's in it |
+|---|---|
+| `tokens.md` | Complete token reference — all colors, spacing, typography, shadows, border radius, z-index |
+| `components.md` | Every component: usage intent, key props, code examples, rules |
+| `screen-patterns.md` | Named layout patterns — list page, detail page, empty state, error state, confirmation dialog, wizard, dashboard |
+| `brand-guidelines.md` | Voice, tone, writing rules, icon style, photography guidance |
+
+---
+
+## Generation Constraints
+
+**Forbidden**
+- Do not invent new components.
+- Do not invent new layout patterns.
+- Do not invent new visual styles.
+- Do not invent new interaction models.
+- Do not invent new token values.
+- Do not substitute a custom solution when a defined component, primitive, or pattern exists.
+
+**Preferred**
+- Use defined Forma 36 components.
+- Use layout primitives: Box, Flex, Stack, Grid.
+- Use tokenized spacing, radius, color, and typography.
+- Use named patterns from screen-patterns.md when applicable.
+
+**Context-dependent**
+- If required information is missing, incomplete, or unspecified:
+  - do not guess beyond the defined system
+  - compose solutions using available primitives and defined components
+  - apply existing rule types and precedence
+  - prefer standard patterns over custom implementations
+
+## Fallback behavior
+
+These rules define how to proceed when required information is missing, incomplete, ambiguous, or in conflict. Apply them with the rule precedence defined in this document.
+
+### Missing component definition
+
+**Required**
+- If a needed component is not defined in this document or the supporting files, do not invent a new component.
+- Compose the UI using defined components and layout primitives only.
+- Prefer the simplest composition that satisfies the requirement using Box, Flex, Stack, Grid, and defined Forma 36 components.
+
+**Forbidden**
+- Do not create a custom component, custom variant, or custom API to fill the gap.
+
+### Missing layout or pattern
+
+**Required**
+- If a needed layout or named pattern is not defined, use the standard application shell defined in this document.
+- Compose the screen from the existing header, content area, sidebar, and layout primitives only.
+- Prefer a standard composition over a custom layout.
+
+**Forbidden**
+- Do not invent a new page pattern, navigation pattern, or layout structure.
+
+### Missing interaction or state behavior
+
+**Required**
+- If a component-specific interaction rule is missing, use the global Interaction states section as the source of truth.
+- Keep behavior minimal and within the defined component model.
+
+**Context-dependent**
+- If a state is not applicable to a component, omit it.
+
+**Forbidden**
+- Do not invent a new interaction model, custom animation, or undefined state behavior.
+
+### Missing accessibility rule
+
+**Required**
+- If a component-specific accessibility rule is missing, apply the explicit accessibility rules already defined in this document for labels, keyboard operation, focus visibility, heading structure, state communication, and text alternatives.
+- Prefer native semantics and documented component APIs over custom accessibility implementations.
+
+**Forbidden**
+- Do not assume undocumented accessibility behavior for a component.
+- Do not remove an accessibility requirement because a component-specific rule is missing.
+
+### Conflicting rules
+
+**Required**
+- Apply rule precedence defined in this document.
+- When rules conflict, the more specific rule wins.
+- When a global rule and a component-specific rule conflict, use the component-specific rule if it does not violate a Forbidden rule.
+
+**Forbidden**
+- Do not merge conflicting rules into a compromise implementation.
+- Do not ignore a Forbidden rule because another rule is less strict.
+
+### Ambiguous or underspecified requirements
+
+**Required**
+- If the requirement is underspecified, select the simplest valid option that is explicitly supported by this document.
+- Prefer defined components over composition, and composition over omission, when both remain within documented rules.
+- If a requirement cannot be satisfied without inventing a component, pattern, behavior, or rule, omit the unsupported part.
+
+**Forbidden**
+- Do not approximate with a “close enough” custom solution.
+- Do not infer undocumented product behavior from philosophy text, examples, or visual style alone.
+
+### Safe default rules
+
+**Required**
+- Stay within defined tokens, defined components, defined patterns, and defined state rules.
+- Prefer standard, lower-complexity compositions over dense or highly customized layouts.
+- Preserve existing explicit constraints even when information is missing elsewhere.
+
+**Forbidden**
+- Do not add decorative UI, auxiliary controls, or optional interactions that are not required by the specification.
+
+## Design Philosophy
+
+This section is non-normative. It explains intent. It does not create requirements, override explicit rules, or permit invention. Use it only to interpret explicit rules elsewhere in this document.
+
+Forma 36 is built on one idea: software should feel calm, trustworthy, and focused.
+
+Supporting principles:
+
+1. **Clarity over cleverness**  
+Prioritize task clarity over decorative or novel presentation.
+
+2. **Restraint as a design decision**  
+Prefer lower visual intensity, clear hierarchy, and semantic use of color.
+
+3. **Consistency builds trust**  
+Prefer existing patterns, consistent spacing, consistent component behavior, and consistent language.
+
+4. **Accessibility is non-negotiable**  
+Apply the explicit accessibility, keyboard, focus, labeling, and state communication rules defined elsewhere in this document.
+
+---
+
+## Visual Language
+
+### Color
+
+| Role | Color | Hex | Use |
+|---|---|---|---|
+| Primary action | Blue 600 | #0059C8 | Primary interactive action |
+| Success / published | Green 600 | #006D23 | Positive outcomes, published state |
+| Danger / error | Red 600 | #BD002A | Destructive actions, errors |
+| Warning / draft | Orange 500 | #CC4500 | Caution, unpublished or draft state |
+| Premium / new | Purple 600 | #6B3DB5 | Paid features |
+| UI surface | Gray 100 | #F7F9FA | Page backgrounds |
+| Panel surface | White | #FFFFFF | Cards, sidebars, modals |
+| Default text | Gray 900 | #111B2B | Body copy, labels |
+| Secondary text | Gray 700 | #414D63 | Section headings, metadata |
+| Muted text | Gray 600 | #536171 | Hints, inactive labels |
+| Borders / dividers | Gray 200 | #E7EBEE | Dividers between sections |
+
+**Supported shade sets**
+- blue100 to blue900
+- gray100 to gray900
+- green100 to green900
+- orange100 to orange900
+- purple100 to purple900
+- red100 to red900
+- yellow100 to yellow900
+
+**Required**
+- Use only supported shade sets and defined color roles.
+- Pair semantic color with text or icon when the color communicates meaning.
+- Use Blue 600 only for primary interactive actions.
+- Use Purple 600 only for paid features.
+- Use blue/100 (#E8F5FF) as the active navigation background.
+- Use black text darker than gray-800 only on shades 100 to 400.
+- Use white text only on shades 500 to 900.
+- For non-yellow same-color foreground/background combinations, use only:
+  - 600 on 100
+  - 600 on 200
+  - 700 on 300
+  - 300 on 900
+  - 500 on white
+  - 500 on gray100
+- For yellow same-color foreground/background combinations, use only:
+  - 800 on 100
+  - 800 on 200
+  - 900 on 300
+  - 300 on 900
+  - 800 on white
+  - 800 on gray100
+
+**Forbidden**
+- Do not use color as decoration.
+- Do not rely on color alone to communicate meaning.
+- Do not use blue for non-interactive decoration.
+- Do not use a blue text color for active navigation items.
+- Do not use unsupported foreground/background shade combinations.
+- Do not use non-yellow same-color combinations outside the allowed set.
+- Do not use yellow same-color combinations outside the allowed yellow set.
+- Do not use yellow when another defined semantic role matches the meaning.
+
+### Typography
+
+| Role | Size | Weight | Use |
+|---|---|---|---|
+| Display | 1.5rem+ | 600 | Page titles, hero text |
+| Section heading | 0.75rem | 600 | Nav group labels, table headers |
+| Body (default) | 0.875rem | 400 | Interface copy |
+| Body medium | 0.875rem | 500 | Emphasized labels |
+| Small / caption | 0.75rem | 400 | Metadata, hints |
+
+**Required**
+- Use Geist as the typeface.
+- Import from https://cdn.f36.contentful.com.
+- Use fallback fonts -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif.
+- Use font-feature-settings: 'ss05' 1 on all Geist text.
+- Use line height 1.5 by default.
+- Use line height 1.25 only for nav items and badges.
+- Use letter spacing 0 for all sizes.
+- Use sentence case for labels.
+
+**Forbidden**
+- Do not mix more than two font weights on a single screen.
+- Do not use Title Case for labels.
+- Do not use ALL CAPS for labels.
+
+### Spacing
+
+| Token | Value | Common use |
+|---|---|---|
+| 2xs | 4px | Icon gaps, tight groupings |
+| xs | 8px | Between related items |
+| s | 12px | Component internal padding |
+| m | 16px | Standard padding |
+| l | 24px | Section padding |
+| xl | 32px | Large section gaps |
+| 2xl | 48px | Page-level separation |
+
+**Required**
+- Use only the defined spacing tokens.
+- Manage external spacing with layout wrappers: Flex, Stack, Box.
+- Use token names on layout components: spacingXs, spacingS, spacingM, etc.
+
+**Forbidden**
+- Do not use arbitrary pixel values for spacing.
+- Do not assign external spacing directly to components.
+
+### Shadows
+
+| Name | Value | Use |
+|---|---|---|
+| Default | 0 0 0 1px rgba(25,37,50,.10), 0 3px 7px -3px rgba(25,37,50,.10), 0 6px 12px -2px rgba(25,37,50,.10) | Panels, sidebar, content area |
+| Button | 0 1px 0 rgba(17,27,43,.05) | Secondary buttons |
+
+**Required**
+- Use Shadow/Default for panels, sidebar, and content area.
+- Use Shadow/Button for secondary buttons.
+
+**Forbidden**
+- Do not create custom shadows.
+- Do not create glows.
+
+### Borders & Radius
+
+| Element | Radius |
+|---|---|
+| Panels, cards | 12px (top corners only for flush-to-edge panels) |
+| Buttons, inputs, nav items | 6px |
+| Small chips, badges | 4px |
+| Avatars | 100px (pill) |
+
+**Required**
+- Use only the defined radius values.
+- Use 12px for panels and cards.
+- Use top corners only for flush-to-edge panels.
+- Use 6px for buttons, inputs, and nav items.
+- Use 4px for small chips and badges.
+- Use 100px for avatars.
+
+**Forbidden**
+- Do not use border radius values outside 4px, 6px, 12px, and 100px.
+
+---
+
+## Base Layout
+
+**Required**
+- Every screen uses this exact shell.
+- Do not invent alternative chrome.
+
+Figma reference: `https://www.figma.com/design/CHqkCTVTpvkqDNXtoAR5cE/Experiences-Library?node-id=6764-6490`
+
+┌──────────────────────────────────────────────────────┐
+│  Top bar  (52px, gray-100 background)                │
+├───────────────┬──────────────────────────────────────┤
+│               │  Content area                        │
+│  Sidebar      │  ┌────────────────────────────────┐  │
+│  (240px)      │  │  Header (title + actions)      │  │
+│               │  ├────────────────────────────────┤  │
+│               │  │  Page content                  │  │
+│               │  └────────────────────────────────┘  │
+└───────────────┴──────────────────────────────────────┘
+[8px agent strip]
+
+### Top bar
+
+**Required**
+- Height: `52px`.
+- Background: `gray/100`.
+- Horizontal padding: `24px` left, `64px` right.
+- The `64px` right gap is reserved for the agent strip.
+- Left content order: Contentful `"C"` logo → Space/Environment switcher pill.
+- Right content order: Search icon → Help icon → User avatar (`24px`).
+- Environment switcher background: `green/100`.
+- Environment switcher border: `green/400`.
+- Environment switcher text: `"Space > Production"` in `green/700`.
+- Environment switcher includes a `green-300` right-edge indicator strip.
+- Environment switcher includes a rocket icon.
+
+**Forbidden**
+- Do not change the top bar height.
+- Keep the top bar content order consistent with the defined structure.
+- Do not use an alternative top bar structure.
+
+### Sidebar
+
+#### Structure
+
+**Required**
+- Sidebar is present in the application shell.
+- Sidebar includes a collapse button.
+- Collapse button is a transparent `IconButton` with `CaretLeft` icon.
+- Collapse button position: bottom-right of sidebar.
+- Sidebar includes all defined sections, items, icons, and states.
+
+**Forbidden**
+- Do not stub the sidebar.
+- Do not simplify the sidebar.
+- Do not remove defined sections, items, icons, or states.
+
+#### Dimensions
+
+**Required**
+- Width: `240px`.
+- Background: `white`.
+- Shadow: `Shadow/Default`.
+- Top corners radius: `12px`.
+- Padding: `pt-12px pb-8px px-4px`.
+- Inner menu padding: `px-12px`.
+- Gap between sections: `12px`.
+- Nav item height: `32px`.
+- Nav item padding: `px-12px py-6px`.
+- Nav item gap: `8px`.
+- Nav item border radius: `4px`.
+- Section title size: `12px`.
+- Section title weight: `600`.
+- Section title color: `gray/700`.
+- Section title height: `28px`.
+- Section title left padding: `pl-12px`.
+
+#### Content
+
+**Required**
+- Sections are separated by `gray/200` bottom border.
+- Sidebar sections and items:
+  1. **Setup** — Design System *(active by default)*, Content Model
+  2. **Creation** — Experiences, Content
+  3. **Optimization** — Optimizations, Analytics
+  4. **Platform Configuration** — Collections, AI & Automations, Taxonomy, Apps
+  5. *(no title)* — Settings
+
+#### States
+
+**Required**
+- See Interaction states.
+- Nav item content: Icon (`16px`, duotone variant for active) + label (body regular, `gray/900`) + optional caret right.
+- Active state background: `blue/100` (`#E8F5FF`).
+- Default state background: transparent.
+- Hover state background: `gray/100`.
+
+#### Constraints
+
+**Required**
+- Implement the sidebar faithfully.
+- Replicate all sections, items, icons, and states exactly.
+
+**Forbidden**
+- Do not modify sidebar structure outside the defined shell.
+- Do not invent additional sidebar patterns.
+
+### Content area
+
+**Required**
+- Content area fills the remaining width.
+- Background: `white`.
+- Shadow: `Shadow/Default`.
+- Top corners radius: `12px`.
+- Padding: `pt-12px px-24px`.
+- `Header` is always present at the top of the content area.
+- Use `Title` variant for top-level pages.
+- Use `Breadcrumb` variant for subpages.
+- Page content is placed below the `Header`.
+
+**Context-dependent**
+- Set `dividerLine={true}` when the content area has a right sidebar.
+
+**Forbidden**
+- Do not omit the `Header`.
+- Do not place page content above the `Header`.
+
+---
+
+## Layout rules
+
+### Layout Primitives
+
+**Required**
+- Use layout primitives to compose all layout structure outside the application shell.
+- Use only Flex, Stack, Box, and Grid for layout composition.
+- Use tokenized spacing values on layout primitives: spacingXs, spacingS, spacingM, spacingL, spacingXl, spacing2Xl.
+- Use layout primitives to control external spacing between components.
+- Keep component external spacing outside the component itself.
+- Keep layout composition inside the existing application shell defined in this document.
+
+**Preferred**
+- Use Stack for one-directional vertical grouping.
+- Use Flex for one-directional layouts that require explicit alignment, justification, or wrapping behavior.
+- Use Grid for two-dimensional layouts with rows and columns.
+- Use Box for single-region containment, padding, margin, width, or other block-level layout control.
+- Use the simplest layout primitive that satisfies the requirement.
+- Prefer Stack over Flex when only directional spacing is required.
+- Prefer Flex over Grid when the layout is one-dimensional.
+
+**Required**
+- Compose layouts from primitives first, then place defined components inside them.
+- Use nested primitives when one primitive cannot express the required structure.
+- Keep DOM order aligned with visual order.
+- Keep page-level spacing, section spacing, and inter-component spacing on layout primitives, not on child components.
+- Use existing shell regions as fixed boundaries: top bar, sidebar, content area, header, page content.
+- Keep the Header at the top of the content area.
+- Place unrestricted page content below the Header.
+
+**Context-dependent**
+- When content requires explicit columns or row/column placement, use Grid.
+- When content is arranged in a single vertical flow, use Stack.
+- When items must be aligned horizontally or distributed along one axis, use Flex.
+- When only padding, margin, width, or a single container wrapper is needed, use Box.
+- When spacing between elements is required, use spacing tokens only.
+- When a right sidebar is present in the content area, follow the existing Header rule for dividerLine={true}.
+- If a layout requirement is underspecified, use the simplest valid composition built from Box, Flex, Stack, and Grid.
+- If a named pattern is missing, compose the layout from the standard application shell and layout primitives only.
+
+**Forbidden**
+- Do not invent new layout primitives.
+- Do not invent new layout patterns outside the application shell and named patterns defined elsewhere in this document.
+- Do not use arbitrary pixel values for layout spacing.
+- Do not use components as layout substitutes when a layout primitive is sufficient.
+- Do not assign external spacing directly to components.
+- Do not use Grid for one-dimensional layouts.
+- Do not use Flex or Stack to approximate a two-dimensional grid layout.
+- Do not break the shell structure defined in Base Layout.
+- Do not reorder DOM structure to create a visual layout that changes reading or interaction order.
+
+---
+
+## Component rules
+
+### Buttons
+
+**Required**
+- Use `Button` for button actions.
+- Use `Primary` for the single most important action in a context. Maximum: one per context.
+- Use `Secondary` for supporting actions.
+- Use `Positive` for constructive actions: create, publish, add.
+- Use `Negative` for destructive or irreversible actions: delete, remove, archive.
+- Use `Transparent` only on light backgrounds.
+- Use native button semantics for button actions.
+- Icon-only actions must use `IconButton` or `ToggleButton` with a descriptive `aria-label`.
+- Button groups must expose an `aria-label`.
+
+**Context-dependent**
+- Use `small` for toolbars.
+- Use `medium` as the default size.
+- Use `large` only for hero CTAs.
+- If a button is marked disabled through a custom button element or `role=button`, click and keydown handlers must not fire.
+- For state behavior, see **Interaction states**.
+- For loading behavior, see **Interaction & State rules**.
+
+**Forbidden**
+- Do not use more than one `Primary` button in the same context.
+
+### Forms
+
+**Required**
+- Every input must live inside a `FormControl`.
+- Structure is always: `Label → Input → Help text → Validation message`.
+- `FormControl.Label` is required.
+- `FormControl.HelpText` is for guidance that always shows.
+- Pass `isRequired`, `isInvalid`, and `isDisabled` to `FormControl`, not to the input directly.
+- Required form elements must be marked programmatically with `isRequired`, not only visually.
+- Help text and validation messages must stay inside the same `FormControl`.
+- `TextInput` and `Textarea` with separate labels must expose `id` for `htmlFor`.
+- Controls used in form submission must expose `name` when submission depends on it.
+- Choose the input type as follows:
+  - Short free text → `TextInput`
+  - Long free text → `Textarea`
+  - Pick one from a short list (`≤8` options) → `Select`
+  - Pick one from a long list → `Autocomplete`
+  - Toggle one option → `Checkbox`
+  - Pick one from a mutually exclusive group → `Radio.Group`
+
+**Context-dependent**
+- `FormControl.ValidationMessage` is for errors and appears only when invalid. See **Feedback selection rules**.
+- If there is no visible label, provide `aria-label` or `aria-labelledby` as supported by the control.
+- Use `Checkbox.Group` or an equivalent fieldset/legend structure for related checkbox options.
+- Use `Radio.Group` to group related radio buttons and provide a group label.
+- If a visible legend is not possible for checkbox or radio groups, use `aria-labelledby`.
+- `Switch` labels must describe the action being controlled.
+- If a visible label is not present for `Select`, provide `aria-label`.
+- Use `Datepicker` inside `FormControl` when label, help text, or validation is needed.
+- Icon-only `Datepicker` trigger buttons must provide a screen-reader label.
+- Disabled or invalid date states must be communicated in text, not only visually.
+- In `Multiselect`, if a visible label is not present, provide an `aria-label`.
+- For state behavior, see **Interaction states**.
+
+**Forbidden**
+- Do not use placeholder text as a replacement for a label.
+
+### Feedback & Status
+
+**Required**
+- Use `Notification` for immediate feedback after a user action.
+- `Notification` dismisses after 6 seconds.
+- `Notification.success('Entry published')` uses active voice and present tense.
+- `Notification.error(...)` must be specific and actionable.
+- Use `Note` for proactive context the user needs before acting.
+- Place `Note` near the relevant content, not at the top of the page generically.
+- Badge labels and status indicators stay to one word.
+- Use `EntityStatusBadge` for Contentful entity status.
+
+**Context-dependent**
+- `Note` variants: neutral, primary, positive, warning, negative, premium.
+- Badge status mapping:
+  - positive = Published
+  - warning = Draft
+  - negative = Deleted
+- For selection logic, see **Feedback selection rules**.
+
+**Forbidden**
+- Do not use `Notification` for persistent context.
+- Do not construct a raw `Badge` for Contentful entity status.
+
+### Navigation & Overlays
+
+**Required**
+- For `Modal` usage, see **Feedback selection rules**.
+- `Modal` content must include a clear title and description.
+- Use `Menu` for actions and navigation choices triggered by a button.
+- `Tabs` navigate between sections of related content.
+- Maximum tabs: `6`.
+- Tab labels must accurately describe the panel content.
+- Provide a unique `panelId` for each tab-panel relationship.
+- `Tooltip` is supplementary, non-critical context.
+- Tooltip content must be short.
+- Always include a unique `id` prop on `Tooltip`.
+- If the trigger is icon-only, the trigger must have its own accessible label independent of the tooltip text.
+
+**Context-dependent**
+- Focus moves into the modal when it opens.
+- Focus remains trapped inside the modal while it is open.
+- Focus returns to the invoking control when the modal closes.
+- Modal dialogs close with `Escape` and outside click unless disabled.
+- Menus move focus into the menu when they open and support keyboard navigation among items.
+- For state behavior, see **Interaction states**.
+
+**Forbidden**
+- Do not use `Select` for actions.
+- Do not put links, buttons, or forms inside a `Tooltip`.
+
+---
+
+## Interaction & State rules
+
+This section defines behavior and interaction rules. Use it with **Component rules**, **Interaction states**, and **Feedback selection rules**. Do not restate component selection or structural rules here.
+
+### Sidebar
+
+**Required**
+- Sidebar navigation uses the global **Interaction states** model.
+- The active item is `Design System` by default.
+- The collapse control is an `IconButton` with `CaretLeft`.
+
+**Context-dependent**
+- Active nav items use `blue/100` (`#E8F5FF`) background fill.
+- Default nav items use transparent background.
+- Hovered nav items use `gray/100` background fill.
+- Active nav items use the duotone icon variant.
+
+### Content area
+
+**Required**
+- See **Base Layout**.
+
+### Buttons
+
+**Required**
+- Buttons use the global **Interaction states** model.
+- Loading uses `isLoading`.
+
+**Forbidden**
+- Do not disable a button and add a spinner manually.
+
+### Forms
+
+**Required**
+- Forms use the global **Interaction states** model.
+
+### Feedback & Status
+
+**Required**
+- See **Feedback selection rules**.
+
+### Navigation & Overlays
+
+**Required**
+- `Modal` behavior follows the global **Interaction states** model.
+- Menus support keyboard navigation among items.
+- Tooltips are non-critical and supplementary.
+
+**Context-dependent**
+- Focus moves into the menu when it opens.
+- Focus moves into the modal when it opens.
+- Focus remains trapped inside the modal while it is open.
+- Focus returns to the invoking control when the modal closes.
+- Modal closes with `Escape` and outside click unless disabled.
+
+### Keyboard and focus
+
+**Required**
+- All interactive elements are keyboard operable.
+- Tab order follows the rendered interaction order.
+
+### Semantic structure and state communication
+
+**Required**
+- Semantic DOM order matches visual order.
+
+### Header and layout accessibility
+
+**Required**
+- Breadcrumbs and back buttons have descriptive accessible labels.
+- Interactive elements placed in header actions or filters are keyboard accessible and clearly labeled.
+- Interactive content placed inside layout containers preserves keyboard navigation and focus management.
+
+**Context-dependent**
+- If multiple headers are present, use the `as` prop to avoid duplicate landmarks and preserve heading hierarchy.
+
+---
+
+## Feedback selection rules
+
+### Selection logic
+
+**Required**
+- Use FormControl.ValidationMessage when the message describes an error on a specific input.
+- Use Note when the message must remain visible while the user reviews or acts on related content.
+- Use Notification when the message confirms the result of a user action and can dismiss after 6 seconds.
+- Use Modal when the user must confirm before proceeding or when the information is essential to the current workflow.
+
+### FormControl.ValidationMessage
+
+**Use when**
+
+**Context-dependent**
+- the message is tied to a specific field
+- the field is invalid
+
+**Do not use when**
+
+**Forbidden**
+- the message applies to the page, section, or workflow rather than a specific input
+- the message is only informational guidance
+
+### Note
+
+**Use when**
+
+**Context-dependent**
+- the message is proactive context the user needs before acting
+- the message must remain visible
+- the message belongs near the relevant content
+
+**Do not use when**
+
+**Forbidden**
+- the message is a field-specific validation error
+- the message is only a temporary action result
+- the message is placed at the top of the page generically
+
+### Notification
+
+**Use when**
+
+**Context-dependent**
+- the message is immediate feedback after a user action
+- the message can dismiss after 6 seconds
+- the message is an action result such as success or error
+
+**Do not use when**
+
+**Forbidden**
+- the message must remain visible while the user works
+- the message is persistent context
+- the message replaces inline validation for a specific field
+
+### Modal
+
+**Use when**
+
+**Context-dependent**
+- the user must confirm before proceeding
+- the information is essential to the current workflow
+- the interaction blocks the interface
+
+**Do not use when**
+
+**Forbidden**
+- the information is non-essential
+- the interaction interrupts high-stakes flows without confirmation need
+- the message is only a transient action result
+- the message is only persistent inline context
+
+### Forbidden patterns
+
+**Forbidden**
+- Do not use Notification for persistent context
+- Do not use Note for field validation
+- Do not use Modal for non-essential information
+- Do not use Modal for a transient success or error message
+- Do not use FormControl.ValidationMessage for page-level or section-level messaging
+
+### Acceptance criteria
+
+**Required**
+- A field-specific error uses FormControl.ValidationMessage
+- A message that must remain visible uses Note
+- A temporary action result uses Notification
+- A blocking confirmation uses Modal
+- Notification messages dismiss after 6 seconds
+- Note is placed near the relevant content
+- FormControl.ValidationMessage appears only when invalid
+- Modal is used only for confirmation before proceeding or information essential to the current workflow
+
+---
+
+## Content & writing
+
+### Writing rules
+
+**Required**
+- Use active voice.
+- Use present tense.
+- Use sentence case everywhere.
+- Start button labels with a verb.
+- Start link labels with a verb when the link is an action.
+- Error messages must state what went wrong and what to do next.
+- Confirmation dialogs for destructive actions must state exactly what will be destroyed.
+
+**Forbidden**
+- Do not use "please".
+- Do not use "click here".
+- Do not use "learn more" without context.
+- Do not use vague single-word labels such as "Go" or "Submit".
+- Do not use Title Case.
+- Do not use ALL CAPS.
+
+**Context-dependent**
+- If a link is navigation rather than an action, the label must describe the destination clearly.
+
+### Button writing rules
+
+**Required**
+- Button labels start with a verb.
+- Maximum button label length: 3 words.
+- The dismiss action for a destructive flow uses Never mind.
+
+**Forbidden**
+- Do not use Cancel as the dismiss action for a destructive flow.
+
+### Modal writing rules
+
+**Required**
+- Modal title format: verb + noun.
+- Confirm button format: verb + noun.
+- Destructive confirmation copy states exactly what will be destroyed.
+- The dismiss action for a destructive flow uses Never mind.
+
+**Forbidden**
+- Do not use a vague modal title.
+- Do not use a vague confirm label.
+- Do not use Cancel as the dismiss action for a destructive flow.
+
+---
+
+## What Forma 36 Never Does
+
+**Forbidden**
+- Do not use decorative color.
+- Do not create custom shadows or glows.
+- Do not use rounded corners outside 4px, 6px, 12px, and 100px.
+- Do not use arbitrary spacing.
+- Do not use Title Case labels.
+- Do not use more than one primary button per screen section.
+- Do not use Button as a link. Use TextLink for navigation.
+- Do not use a bare Badge for entity status. Use EntityStatusBadge.
+- Do not use Notification for persistent context. Use Note and follow **Feedback selection rules**.
+- Do not place interactive elements inside Tooltip content.
+- Do not omit the Header from a page.
+- Do not use Workbench. Use Layout.
+- Do not use raw hex colors in code. Use tokens from @contentful/f36-tokens.

From f0032bed983de76434fc53a241f5810e5b8c0198 Mon Sep 17 00:00:00 2001
From: damann <67584870+damann@users.noreply.github.com>
Date: Mon, 13 Apr 2026 16:24:17 +0200
Subject: [PATCH 02/13] Rename forma-36-skill to SKILL.md

---
 skill/forma-36-skill => skills/SKILL.md | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename skill/forma-36-skill => skills/SKILL.md (100%)

diff --git a/skill/forma-36-skill b/skills/SKILL.md
similarity index 100%
rename from skill/forma-36-skill
rename to skills/SKILL.md

From e3e3ff330e1e5c8ffc54efbb2af9da7115670c77 Mon Sep 17 00:00:00 2001
From: damann <67584870+damann@users.noreply.github.com>
Date: Mon, 13 Apr 2026 16:25:51 +0200
Subject: [PATCH 03/13] Add tokens skill

This file contains design tokens for Forma 36, including color, spacing, typography, shadow, border radius, and z-index tokens. It emphasizes the use of token names instead of raw values to maintain consistency with the design system.
---
 skills/tokens.md | 218 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 218 insertions(+)
 create mode 100644 skills/tokens.md

diff --git a/skills/tokens.md b/skills/tokens.md
new file mode 100644
index 0000000000..3d856b03d9
--- /dev/null
+++ b/skills/tokens.md
@@ -0,0 +1,218 @@
+# Forma 36 — Design Tokens
+
+All values come from `@contentful/f36-tokens`. Never use raw hex values or arbitrary numbers in code — always use the token name. This ensures the UI stays in sync with the design system.
+
+```js
+import tokens from '@contentful/f36-tokens';
+// or individual tokens:
+import { colorPrimary, spacingM } from '@contentful/f36-tokens';
+```
+
+---
+
+## Color Tokens
+
+### Semantic (use these first)
+
+These are the tokens to reach for by default. They express intent, not shade.
+
+| Token | Value | Meaning |
+|---|---|---|
+| `colorPrimary` | `#0059C8` | Primary interactive actions, links |
+| `colorPositive` | `#006D23` | Success, published state, constructive |
+| `colorNegative` | `#BD002A` | Errors, destructive actions, deleted |
+| `colorWarning` | `#CC4500` | Warnings, draft/unpublished state |
+| `colorTextDark` | `#111B2B` | Primary text — highest contrast |
+| `colorTextBase` | `#1B273A` | Default body text |
+| `colorTextMid` | `#414D63` | Secondary labels, section titles |
+| `colorTextLight` | `#5A657C` | Tertiary text, captions |
+| `colorTextLightest` | `#67728A` | Placeholder text, inactive |
+
+### Gray Scale
+
+Used for surfaces, borders, and text.
+
+| Token | Hex | Common use |
+|---|---|---|
+| `gray100` | `#F7F9FA` | Page background |
+| `gray200` | `#E7EBEE` | Dividers, subtle borders |
+| `gray300` | `#CFD9E0` | Borders, input outlines |
+| `gray400` | `#B4C3CC` | Disabled borders |
+| `gray500` | `#8D9BA6` | Muted icons |
+| `gray600` | `#536171` | Muted/secondary icons |
+| `gray700` | `#414D63` | Section heading text |
+| `gray800` | `#2A3546` | Strong secondary text |
+| `gray900` | `#111B2B` | Primary text, nav labels |
+
+### Blue (Primary)
+
+| Token | Hex | Common use |
+|---|---|---|
+| `blue100` | `#E8F5FF` | Active nav item background |
+| `blue200` | `#CCE9FF` | Hover on primary elements |
+| `blue300` | `#A0D2FD` | — |
+| `blue400` | `#62B0F8` | — |
+| `blue500` | `#036FE3` | — |
+| `blue600` | `#0059C8` | **Primary action color** — buttons, links, active icons |
+| `blue700` | `#0044A8` | Pressed state |
+| `blue800` | `#003080` | — |
+| `blue900` | `#002A8E` | — |
+
+### Green (Positive)
+
+| Token | Hex | Common use |
+|---|---|---|
+| `green100` | `#EAF9E8` | Environment switcher background |
+| `green300` | `#9ED696` | Environment type indicator strip |
+| `green400` | `#5DB057` | Environment switcher border |
+| `green600` | `#006D23` | Published status, success text |
+| `green700` | `#00550C` | Environment switcher text |
+
+### Red (Negative)
+
+| Token | Hex | Common use |
+|---|---|---|
+| `red100` | `#FFF2F2` | Error field background |
+| `red600` | `#BD002A` | Error text, destructive button |
+| `red700` | `#9A0020` | Pressed destructive state |
+
+### Orange (Warning)
+
+| Token | Hex | Common use |
+|---|---|---|
+| `orange100` | `#FFF2E4` | Warning note background |
+| `orange400` | `#F07C00` | Warning icons |
+| `orange500` | `#CC4500` | Draft/unpublished state, warning text |
+
+### Purple (Premium — use sparingly)
+
+| Token | Hex | Common use |
+|---|---|---|
+| `purple100` | `#F7F2FF` | Premium feature background |
+| `purple600` | `#8553E7` | Premium label, "new feature" highlight |
+
+### Yellow (last resort only)
+
+| Token | Hex | Note |
+|---|---|---|
+| `yellow400` | `#FFC835` | Only when all other options fail |
+
+### Absolute
+
+| Token | Hex |
+|---|---|
+| `colorWhite` | `#FFFFFF` |
+| `colorBlack` | `#0C141C` |
+
+---
+
+## Spacing Tokens
+
+Components carry no external margin. Use these to create space between elements.
+
+| Token | Value | Rem |
+|---|---|---|
+| `spacing2Xs` | 4px | 0.25rem |
+| `spacingXs` | 8px | 0.5rem |
+| `spacingS` | 12px | 0.75rem |
+| `spacingM` | 16px | 1rem |
+| `spacingL` | 24px | 1.5rem |
+| `spacingXl` | 32px | 2rem |
+| `spacing2Xl` | 48px | 3rem |
+| `spacing3Xl` | 64px | 4rem |
+| `spacing4Xl` | 80px | 5rem |
+
+**Usage:**
+```js
+// Inline style
+<div style={{ padding: tokens.spacingM }} />
+
+// Layout component prop
+<Stack spacing="spacingM" />
+<Flex gap="spacingS" />
+```
+
+---
+
+## Typography Tokens
+
+### Font Families
+
+| Token | Stack |
+|---|---|
+| `fontStackPrimary` | `Geist Sans, -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial, sans-serif` |
+| `fontStackMonospace` | `Geist Mono, SFMono-Regular, Consolas, Liberation Mono, Menlo, monospace` |
+
+Geist is loaded from `https://cdn.f36.contentful.com`. Always use `fontStackPrimary` — never hardcode `Geist` alone without the fallback stack.
+
+### Font Sizes
+
+| Token | Value | Use |
+|---|---|---|
+| `fontSize4Xl` | 3rem | Hero display text |
+| `fontSize3Xl` | 2.25rem | Large display |
+| `fontSize2Xl` | 1.5rem | Page-level headings |
+| `fontSizeXl` | 1.25rem | Section headings |
+| `fontSizeL` | 1rem | Large body |
+| `fontSizeM` | 0.875rem | **Default body** — most interface text |
+| `fontSizeS` | 0.75rem | Captions, metadata, section labels |
+
+### Font Weights
+
+| Token | Value | Use |
+|---|---|---|
+| `fontWeightNormal` | 400 | All body text |
+| `fontWeightMedium` | 500 | Emphasized labels, active states |
+| `fontWeightDemiBold` | 600 | Headings, section titles, nav group labels |
+
+### Line Heights
+
+| Token | Value | Use |
+|---|---|---|
+| `lineHeightDefault` | 1.5 | Body text |
+| `lineHeightCondensed` | 1.25 | Nav items, badges, compact UI |
+
+### Letter Spacing
+
+| Token | Value |
+|---|---|
+| `letterSpacingDefault` | 0rem |
+| `letterSpacingWide` | 0.1rem |
+
+Forma 36 uses `0` letter spacing by default. Do not add tracking to Geist.
+
+---
+
+## Shadow Tokens
+
+| Name | CSS Value | Use |
+|---|---|---|
+| `shadowDefault` | `0 0 0 1px rgba(25,37,50,.10), 0 3px 7px -3px rgba(25,37,50,.10), 0 6px 12px -2px rgba(25,37,50,.10)` | Panels, sidebar, content area, cards |
+| `shadowButton` | `0 1px 0 rgba(17,27,43,.05)` | Secondary and transparent buttons |
+
+Only these two shadows exist in Forma 36. Do not invent custom shadows.
+
+---
+
+## Border Radius Tokens
+
+| Token | Value | Use |
+|---|---|---|
+| `borderRadiusSmall` | 4px | Nav items, badges, small chips |
+| `borderRadiusMedium` | 6px | Buttons, inputs, menus |
+| `borderRadiusLarge` | 12px | Panels, cards, modals |
+| `borderRadiusPill` | 100px | Avatars, pill badges |
+
+Top-only radius (panels flush to bottom edge): apply `border-radius: 12px 12px 0 0`.
+
+---
+
+## Z-Index Tokens
+
+| Token | Value | Use |
+|---|---|---|
+| `zIndexDefault` | 0 | Normal flow |
+| `zIndexSticky` | 101 | Sticky headers |
+| `zIndexDropdown` | 200 | Menus, dropdowns |
+| `zIndexModal` | 1000 | Modals, dialogs |
+| `zIndexNotification` | 9000 | Toast notifications |

From 4c6d7c78369fdc82b5278c7317285d1aadfc8879 Mon Sep 17 00:00:00 2001
From: damann <67584870+damann@users.noreply.github.com>
Date: Mon, 13 Apr 2026 16:27:25 +0200
Subject: [PATCH 04/13] Add UI Patterns skill

---
 skills/ui-patterns.md | 255 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 255 insertions(+)
 create mode 100644 skills/ui-patterns.md

diff --git a/skills/ui-patterns.md b/skills/ui-patterns.md
new file mode 100644
index 0000000000..e2a89d6d71
--- /dev/null
+++ b/skills/ui-patterns.md
@@ -0,0 +1,255 @@
+# Forma 36 — UI Patterns
+
+Named, reusable patterns for the most common Contentful UI screens. When a design calls for one of these, use this as the structural template — not a blank canvas.
+
+---
+
+## 1. List / Index Page
+
+The most common pattern in Contentful. A collection of items (entries, content types, assets, apps) with filtering and primary action.
+
+```
+Header
+  title: "Experiences"
+  actions: [secondary button, primary button]
+  filters: [search input, optional filter selects]
+
+Content area
+  ├── Bulk action bar (appears when items are selected)
+  ├── Table or EntityList
+  │     rows: [thumbnail?, title, metadata columns, status badge, actions menu]
+  └── Pagination
+```
+
+**Rules:**
+- Primary action ("Create experience") is always top-right in the Header
+- Empty state shows when no items exist OR when search returns no results (different messages for each)
+- Row actions via `Menu` with `IconButton` trigger (MoreHorizontal icon) — not inline buttons
+- Status column uses `EntityStatusBadge`
+- Bulk selection: checkbox column left, bulk action bar appears above table
+- Loading state: show `Skeleton.Row` inside the table body
+
+**Empty state (no items):**
+- Heading: "No [items] yet"
+- Body: one sentence describing the purpose of this section
+- Action: primary button to create the first item
+
+**Empty state (filtered, no results):**
+- Heading: "No results for "[query]""
+- Body: "Try a different search term or clear filters."
+- Action: TextLink "Clear filters"
+
+---
+
+## 2. Detail / Edit Page
+
+A single entity being viewed or edited. Common for entries, content types, experience editors.
+
+```
+Header
+  title: entry name (or "Untitled" if new)
+  breadcrumbs: [parent section]
+  actions: [secondary actions menu, "Save" or "Publish" primary]
+
+Content area (two-column when sidebar present)
+  ├── Main content area (fields, editor, canvas)
+  └── Right sidebar: status, metadata, publish controls, linked entries
+```
+
+**Rules:**
+- `dividerLine={true}` on Header when right sidebar is present
+- Status in sidebar uses `EntityStatusBadge`
+- Publish button is `positive` variant — "Publish"
+- Save draft is `secondary` — "Save"
+- Unsaved changes: show a `Note variant="warning"` below the Header, not a blocking modal
+- Discard changes: show a confirmation Modal before navigating away
+
+---
+
+## 3. Settings Page
+
+Configuration of a feature, app, or space setting.
+
+```
+Header
+  title: "[Feature] settings"
+  actions: [optional "Save changes" primary button]
+
+Content area
+  ├── Optional: Tabs (if settings have distinct categories)
+  ├── Sections with Heading separator
+  │     ├── FormControl fields
+  │     └── Optional Note for context
+  └── Danger zone section (at bottom, with negative Note)
+        └── Destructive actions (delete, reset, disable)
+```
+
+**Rules:**
+- Group related settings under a `Heading` or `SectionHeading` with a `gray/200` divider
+- Danger zone (destructive actions) always goes at the very bottom, separated visually
+- Destructive actions in danger zone: `negative` variant `Button`, always trigger a confirmation Modal
+- Inline save: show `Notification.success` after saving — don't navigate away
+- Auto-save: show a subtle "Saving…" Spinner + "Saved" text near the field or in a status area
+
+---
+
+## 4. Empty State
+
+Used when a section has no content yet — first-time experience, no search results, or after clearing filters.
+
+```
+Centered container (vertical + horizontal center of content area)
+  ├── Icon (optional): 48px, gray/400, relevant to the section
+  ├── Heading: "No [items] yet"
+  ├── Body: one sentence describing purpose or next step
+  └── Primary action: Button variant="primary" or TextLink
+```
+
+**Heading formulas:**
+- First-time: "No [content types] yet"
+- No search results: `No results for "[query]"`
+- Permission-restricted: "You don't have access to [section]"
+
+**Body formulas:**
+- First-time: "[Section] lets you [what it does]. Start by [first action]."
+- No results: "Try a different search term or [adjust filters]."
+- Error: "Something went wrong while loading [items]. [Retry link]."
+
+**Rules:**
+- Never show an empty state while data is still loading — show Skeleton instead
+- Never show a generic "No data" — always be specific about what's missing and what to do
+- Keep body copy to one sentence
+- Only one action in an empty state — the most obvious next step
+
+---
+
+## 5. Error State
+
+When a page or section fails to load or an operation fails unrecoverably.
+
+```
+Centered container
+  ├── Icon: WarningIcon or CloseCircleIcon, 48px, red/600
+  ├── Heading: "Couldn't load [section]"
+  ├── Body: brief explanation + what the user can do
+  └── Actions: "Try again" (primary) + optional "Go back" (secondary)
+```
+
+**Rules:**
+- "Couldn't load" not "Error 500" or technical codes — humanize
+- Always offer a clear recovery action ("Try again", "Go back", "Contact support")
+- Log technical details to console; show human language in the UI
+- For partial failures (one section fails, rest loads): use `Note variant="negative"` inline, not a full-page error
+
+---
+
+## 6. Confirmation Dialog (Destructive Action)
+
+Triggered before any irreversible action.
+
+```
+Modal size="small"
+  Header: "[Delete/Remove/Archive] [item type]"
+  Content:
+    Paragraph: "This will permanently [consequence]. This cannot be undone."
+    Optional: list of what will be affected
+  Controls:
+    Button variant="negative": "[Delete/Remove/Archive] [item type]"
+    Button variant="secondary": "Never mind"
+```
+
+**Rules:**
+- Title and confirm button always match: same verb + noun
+- Confirm button is `negative` variant — always
+- Cancel is always "Never mind" — never "Cancel", "No", or "Go back"
+- Body: state the consequence specifically — never vague ("This action cannot be undone")
+- `shouldCloseOnOverlayClick={false}` for destructive modals — user must make an explicit choice
+- Confirm button shows `isLoading` while the action is in flight
+
+---
+
+## 7. Multi-Step Flow / Wizard
+
+Onboarding, content type creation, or any guided multi-step process.
+
+```
+Layout variant="narrow" or Modal size="large" / "fullscreen"
+  ├── Step indicator (top, horizontal) — "Step 2 of 4"
+  ├── Header: step title
+  ├── Content: step-specific form or information
+  └── Footer controls:
+        ├── Left: "Back" (secondary, or hidden on step 1)
+        └── Right: "Continue" (primary) or "Finish" (positive, last step)
+```
+
+**Rules:**
+- "Back" on left, "Continue" on right — never reversed
+- Final step confirm button: `positive` variant — "Create [thing]" or "Finish setup"
+- Show a progress indicator (step count or progress bar) — never leave users wondering how long the flow is
+- Validate before allowing "Continue" — show `ValidationMessage` inline, not a blocking alert
+- Allow exiting the flow — show discard confirmation if data has been entered
+
+---
+
+## 8. Dashboard / Overview Page
+
+High-level summary of a space or feature — metrics, recent activity, quick actions.
+
+```
+Header
+  title: "Overview" or space/project name
+  actions: optional primary CTA
+
+Content area
+  ├── Row of metric Cards (3–4 columns)
+  ├── Recent activity list or EntityList
+  └── Quick action Cards or links
+```
+
+**Rules:**
+- Cards in metric rows: equal width, consistent padding `default`
+- No more than 4 metric cards in a row before wrapping or reorganizing into a different layout
+- "Recent activity" shows last 5–10 items — link to full list
+- Loading: show `Skeleton.Container` per card, not a full-page spinner
+- Empty state per section independently — not one global empty state for the whole dashboard
+
+---
+
+## 9. Form Page (Standalone)
+
+A dedicated page for a single form — app configuration, user preferences, invite flow.
+
+```
+Layout variant="narrow"
+  Header: form title
+  Content:
+    Stack of FormControl fields (spacing="spacingM")
+    Optional: Note for context or instructions
+    Optional: Accordion for advanced/optional sections
+  Footer or inline:
+    Button variant="primary": "Save" or "Submit"
+    Optional Button variant="secondary": "Cancel" (navigates back)
+```
+
+**Rules:**
+- Use `Layout variant="narrow"` to keep forms readable — never stretch a form to full width
+- Group related fields under a `Heading` — don't list 15 fields in one undifferentiated block
+- Required fields: mark with `isRequired` on `FormControl` — the asterisk appears automatically
+- Validation: inline, on blur or on submit — never a separate error summary page
+- On success: `Notification.success` + navigate to the result, or stay on form with a success state
+
+---
+
+## Navigation Hierarchy
+
+When building multi-level navigation:
+
+| Level | Pattern |
+|---|---|
+| Top-level sections | Left sidebar `M1NavigationSidebarMain` sections |
+| Sub-sections within a section | Tabs in the content area |
+| Drill-down to a single item | Header with Breadcrumb + back button |
+| Related views on a single item | Tabs in the detail page content area |
+
+**Never use modals as navigation.** A modal should complete a task, not replace a page.
+**Never use Tabs at the sidebar level** — sidebar items navigate between sections, not tabs.

From 7286e2b21715214cf5644110f673b06de94804b7 Mon Sep 17 00:00:00 2001
From: damann <67584870+damann@users.noreply.github.com>
Date: Mon, 13 Apr 2026 16:28:47 +0200
Subject: [PATCH 05/13] small formatting change in SKILL

Add description for Forma 36 UI design system.
---
 skills/SKILL.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/skills/SKILL.md b/skills/SKILL.md
index 9b4628a783..f918251b35 100644
--- a/skills/SKILL.md
+++ b/skills/SKILL.md
@@ -1,3 +1,4 @@
+---
 name: forma36
 description: Build UI using Forma 36, Contentful's design system. Use when the user references Forma 36, f36, Contentful components, or wants to build a Contentful app UI — including prototypes, screens, and interface explorations.
 ---

From 0af84aa964fcfeb360ee34fe49a2a4d10aef1ad5 Mon Sep 17 00:00:00 2001
From: damann <67584870+damann@users.noreply.github.com>
Date: Mon, 13 Apr 2026 16:30:30 +0200
Subject: [PATCH 06/13] Rename ui-patterns.md to screen-patterns.md

---
 skills/{ui-patterns.md => screen-patterns.md} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename skills/{ui-patterns.md => screen-patterns.md} (100%)

diff --git a/skills/ui-patterns.md b/skills/screen-patterns.md
similarity index 100%
rename from skills/ui-patterns.md
rename to skills/screen-patterns.md

From 83fcb724bc5fbeec90b220c7be3c12efd59da319 Mon Sep 17 00:00:00 2001
From: damann <67584870+damann@users.noreply.github.com>
Date: Mon, 13 Apr 2026 16:30:50 +0200
Subject: [PATCH 07/13] Rename UI Patterns to Screen Patterns

Updated the title to reflect 'Screen Patterns' instead of 'UI Patterns'.
---
 skills/screen-patterns.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/skills/screen-patterns.md b/skills/screen-patterns.md
index e2a89d6d71..7d3c57e189 100644
--- a/skills/screen-patterns.md
+++ b/skills/screen-patterns.md
@@ -1,4 +1,4 @@
-# Forma 36 — UI Patterns
+# Forma 36 — Screen Patterns
 
 Named, reusable patterns for the most common Contentful UI screens. When a design calls for one of these, use this as the structural template — not a blank canvas.
 

From 39f680ef06308b195b85417c35578422385a3fe4 Mon Sep 17 00:00:00 2001
From: toniwowtscherk <toni.wowtscherk@contentful.com>
Date: Fri, 17 Apr 2026 09:56:29 +0200
Subject: [PATCH 08/13] Restructure Forma 36 skill into granular Make Kit
 format
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace the monolithic SKILL.md/tokens.md/screen-patterns.md with a
structured guidelines/ directory following Figma Make Kit best practices
(many short, focused files over few large ones).

New structure:
- guidelines/tokens/ — color, typography, spacing, effects
- guidelines/components/ — layout, buttons, forms, feedback, navigation,
  data-display, content-media, utility
- guidelines/composition/ — base shell, 9 screen patterns
- guidelines/foundations/ — writing, icons, accessibility
- examples/ — 6 TSX reference implementations (list, detail, settings,
  confirmation, form, error)

SKILL.md now routes two audiences:
- Path A (designers): composition-first, visual-language focused
- Path B (developers): setup-first, prop-precision focused

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 skills/SKILL.md                               | 946 +++---------------
 skills/examples/confirmation-dialog.tsx       |  50 +
 skills/examples/detail-page.tsx               |  84 ++
 skills/examples/error-state.tsx               |  37 +
 skills/examples/form-page.tsx                 | 108 ++
 skills/examples/list-page.tsx                 | 146 +++
 skills/examples/settings-page.tsx             |  84 ++
 skills/guidelines/components/buttons.md       |  87 ++
 skills/guidelines/components/content-media.md |  65 ++
 skills/guidelines/components/data-display.md  | 145 +++
 skills/guidelines/components/feedback.md      |  96 ++
 skills/guidelines/components/forms.md         | 156 +++
 skills/guidelines/components/layout.md        | 139 +++
 skills/guidelines/components/navigation.md    | 133 +++
 skills/guidelines/components/overview.md      |  60 ++
 skills/guidelines/components/utility.md       |  88 ++
 skills/guidelines/composition/base-shell.md   |  66 ++
 skills/guidelines/composition/overview.md     |  14 +
 .../guidelines/composition/screen-patterns.md | 210 ++++
 .../guidelines/foundations/accessibility.md   |  42 +
 skills/guidelines/foundations/icons.md        |  47 +
 skills/guidelines/foundations/overview.md     |   9 +
 skills/guidelines/foundations/writing.md      |  86 ++
 skills/guidelines/overview.md                 |  36 +
 skills/guidelines/setup.md                    |  59 ++
 skills/guidelines/tokens/color.md             | 117 +++
 skills/guidelines/tokens/effects.md           |  72 ++
 skills/guidelines/tokens/overview.md          |  25 +
 skills/guidelines/tokens/spacing.md           |  54 +
 skills/guidelines/tokens/typography.md        |  79 ++
 skills/screen-patterns.md                     | 255 -----
 skills/tokens.md                              | 218 ----
 32 files changed, 2517 insertions(+), 1296 deletions(-)
 create mode 100644 skills/examples/confirmation-dialog.tsx
 create mode 100644 skills/examples/detail-page.tsx
 create mode 100644 skills/examples/error-state.tsx
 create mode 100644 skills/examples/form-page.tsx
 create mode 100644 skills/examples/list-page.tsx
 create mode 100644 skills/examples/settings-page.tsx
 create mode 100644 skills/guidelines/components/buttons.md
 create mode 100644 skills/guidelines/components/content-media.md
 create mode 100644 skills/guidelines/components/data-display.md
 create mode 100644 skills/guidelines/components/feedback.md
 create mode 100644 skills/guidelines/components/forms.md
 create mode 100644 skills/guidelines/components/layout.md
 create mode 100644 skills/guidelines/components/navigation.md
 create mode 100644 skills/guidelines/components/overview.md
 create mode 100644 skills/guidelines/components/utility.md
 create mode 100644 skills/guidelines/composition/base-shell.md
 create mode 100644 skills/guidelines/composition/overview.md
 create mode 100644 skills/guidelines/composition/screen-patterns.md
 create mode 100644 skills/guidelines/foundations/accessibility.md
 create mode 100644 skills/guidelines/foundations/icons.md
 create mode 100644 skills/guidelines/foundations/overview.md
 create mode 100644 skills/guidelines/foundations/writing.md
 create mode 100644 skills/guidelines/overview.md
 create mode 100644 skills/guidelines/setup.md
 create mode 100644 skills/guidelines/tokens/color.md
 create mode 100644 skills/guidelines/tokens/effects.md
 create mode 100644 skills/guidelines/tokens/overview.md
 create mode 100644 skills/guidelines/tokens/spacing.md
 create mode 100644 skills/guidelines/tokens/typography.md
 delete mode 100644 skills/screen-patterns.md
 delete mode 100644 skills/tokens.md

diff --git a/skills/SKILL.md b/skills/SKILL.md
index f918251b35..f0a6eac0b6 100644
--- a/skills/SKILL.md
+++ b/skills/SKILL.md
@@ -1,875 +1,175 @@
 ---
 name: forma36
-description: Build UI using Forma 36, Contentful's design system. Use when the user references Forma 36, f36, Contentful components, or wants to build a Contentful app UI — including prototypes, screens, and interface explorations.
+description: >
+  Forma 36 — Contentful's design system. Tokens, components, composition patterns,
+  writing rules, and reference implementations for AI agents building Contentful UI.
+  Use when the user references Forma 36, f36, Contentful components, or wants to
+  build a Contentful app UI.
 ---
 
 # Forma 36 — Contentful Design System
 
-Forma 36 is the design language of Contentful. Every prototype, screen, and component built for Contentful must look and feel like it belongs in the Contentful product. This skill ensures that.
+Forma 36 is the design language of Contentful. Every screen, component, and interaction built for Contentful must look and feel like it belongs in the product — calm, trustworthy, and focused on the user's task.
 
-The goal is not to use the right component name — it's to produce UI that is indistinguishable from the real Contentful interface.
-
-## Scope, Authority, and Rule Interpretation
-
-This document is the primary operational specification for generating UI with Forma 36.
-
-Use it to determine:
-- which UI structures are allowed
-- which components and patterns to use
-- which visual and writing rules are mandatory
-- which implementations are forbidden
-
-This is a normative specification. Outputs must follow explicit rules. Philosophy sections explain intent but do not override rules or permit invention.
-
----
-
-## Rule Types
-
-All guidance is expressed using the following rule types:
-
-- **Required** — mandatory in every applicable case. Treat as pass/fail.
-- **Forbidden** — never allowed. If present, the UI is incorrect.
-- **Preferred** — default choice unless a more specific rule overrides it.
-- **Context-dependent** — mandatory only when the stated condition is true.
-
-### Rule precedence
-
-Apply rules in this order:
-1. Forbidden
-2. Required
-3. Context-dependent (when condition is true)
-4. Preferred
-5. Philosophy and explanatory text
-
-When applying rules:
-- apply conditional rules only when their condition is true
-- when rules conflict, the more specific rule wins
-- Forbidden rules always take precedence
-
-Only explicit rules, named components, defined patterns, and tokenized values are normative.
-
----
-
-## Supporting Files
-
-Supporting files extend this specification with domain-specific detail.
-
-Apply them as follows:
-- use this document first to determine structure and rule intent
-- use the relevant supporting file for detailed decisions
-- when rules do not conflict, apply both
-- when rules conflict, the more specific rule wins
-
-This skill is split across four reference files. Read the relevant one for the task at hand:
-
-| File | What's in it |
-|---|---|
-| `tokens.md` | Complete token reference — all colors, spacing, typography, shadows, border radius, z-index |
-| `components.md` | Every component: usage intent, key props, code examples, rules |
-| `screen-patterns.md` | Named layout patterns — list page, detail page, empty state, error state, confirmation dialog, wizard, dashboard |
-| `brand-guidelines.md` | Voice, tone, writing rules, icon style, photography guidance |
+**Docs:** https://f36.contentful.com
+**Source:** https://github.com/contentful/forma-36
 
 ---
 
-## Generation Constraints
-
-**Forbidden**
-- Do not invent new components.
-- Do not invent new layout patterns.
-- Do not invent new visual styles.
-- Do not invent new interaction models.
-- Do not invent new token values.
-- Do not substitute a custom solution when a defined component, primitive, or pattern exists.
-
-**Preferred**
-- Use defined Forma 36 components.
-- Use layout primitives: Box, Flex, Stack, Grid.
-- Use tokenized spacing, radius, color, and typography.
-- Use named patterns from screen-patterns.md when applicable.
-
-**Context-dependent**
-- If required information is missing, incomplete, or unspecified:
-  - do not guess beyond the defined system
-  - compose solutions using available primitives and defined components
-  - apply existing rule types and precedence
-  - prefer standard patterns over custom implementations
-
-## Fallback behavior
-
-These rules define how to proceed when required information is missing, incomplete, ambiguous, or in conflict. Apply them with the rule precedence defined in this document.
-
-### Missing component definition
-
-**Required**
-- If a needed component is not defined in this document or the supporting files, do not invent a new component.
-- Compose the UI using defined components and layout primitives only.
-- Prefer the simplest composition that satisfies the requirement using Box, Flex, Stack, Grid, and defined Forma 36 components.
+## Choose your path
 
-**Forbidden**
-- Do not create a custom component, custom variant, or custom API to fill the gap.
+This skill serves two audiences. Pick the one that matches your task, then follow its reading order.
 
-### Missing layout or pattern
+### Path A — Designer prototyping
 
-**Required**
-- If a needed layout or named pattern is not defined, use the standard application shell defined in this document.
-- Compose the screen from the existing header, content area, sidebar, and layout primitives only.
-- Prefer a standard composition over a custom layout.
-
-**Forbidden**
-- Do not invent a new page pattern, navigation pattern, or layout structure.
-
-### Missing interaction or state behavior
-
-**Required**
-- If a component-specific interaction rule is missing, use the global Interaction states section as the source of truth.
-- Keep behavior minimal and within the defined component model.
-
-**Context-dependent**
-- If a state is not applicable to a component, omit it.
-
-**Forbidden**
-- Do not invent a new interaction model, custom animation, or undefined state behavior.
-
-### Missing accessibility rule
-
-**Required**
-- If a component-specific accessibility rule is missing, apply the explicit accessibility rules already defined in this document for labels, keyboard operation, focus visibility, heading structure, state communication, and text alternatives.
-- Prefer native semantics and documented component APIs over custom accessibility implementations.
-
-**Forbidden**
-- Do not assume undocumented accessibility behavior for a component.
-- Do not remove an accessibility requirement because a component-specific rule is missing.
-
-### Conflicting rules
-
-**Required**
-- Apply rule precedence defined in this document.
-- When rules conflict, the more specific rule wins.
-- When a global rule and a component-specific rule conflict, use the component-specific rule if it does not violate a Forbidden rule.
-
-**Forbidden**
-- Do not merge conflicting rules into a compromise implementation.
-- Do not ignore a Forbidden rule because another rule is less strict.
-
-### Ambiguous or underspecified requirements
-
-**Required**
-- If the requirement is underspecified, select the simplest valid option that is explicitly supported by this document.
-- Prefer defined components over composition, and composition over omission, when both remain within documented rules.
-- If a requirement cannot be satisfied without inventing a component, pattern, behavior, or rule, omit the unsupported part.
-
-**Forbidden**
-- Do not approximate with a “close enough” custom solution.
-- Do not infer undocumented product behavior from philosophy text, examples, or visual style alone.
-
-### Safe default rules
-
-**Required**
-- Stay within defined tokens, defined components, defined patterns, and defined state rules.
-- Prefer standard, lower-complexity compositions over dense or highly customized layouts.
-- Preserve existing explicit constraints even when information is missing elsewhere.
-
-**Forbidden**
-- Do not add decorative UI, auxiliary controls, or optional interactions that are not required by the specification.
-
-## Design Philosophy
-
-This section is non-normative. It explains intent. It does not create requirements, override explicit rules, or permit invention. Use it only to interpret explicit rules elsewhere in this document.
-
-Forma 36 is built on one idea: software should feel calm, trustworthy, and focused.
-
-Supporting principles:
-
-1. **Clarity over cleverness**  
-Prioritize task clarity over decorative or novel presentation.
-
-2. **Restraint as a design decision**  
-Prefer lower visual intensity, clear hierarchy, and semantic use of color.
-
-3. **Consistency builds trust**  
-Prefer existing patterns, consistent spacing, consistent component behavior, and consistent language.
-
-4. **Accessibility is non-negotiable**  
-Apply the explicit accessibility, keyboard, focus, labeling, and state communication rules defined elsewhere in this document.
-
----
+You are designing a screen, vibe-coding a prototype, or exploring a UI concept in Figma Make. You care about how it *looks and feels* — layout, visual language, screen structure, copy.
 
-## Visual Language
-
-### Color
-
-| Role | Color | Hex | Use |
-|---|---|---|---|
-| Primary action | Blue 600 | #0059C8 | Primary interactive action |
-| Success / published | Green 600 | #006D23 | Positive outcomes, published state |
-| Danger / error | Red 600 | #BD002A | Destructive actions, errors |
-| Warning / draft | Orange 500 | #CC4500 | Caution, unpublished or draft state |
-| Premium / new | Purple 600 | #6B3DB5 | Paid features |
-| UI surface | Gray 100 | #F7F9FA | Page backgrounds |
-| Panel surface | White | #FFFFFF | Cards, sidebars, modals |
-| Default text | Gray 900 | #111B2B | Body copy, labels |
-| Secondary text | Gray 700 | #414D63 | Section headings, metadata |
-| Muted text | Gray 600 | #536171 | Hints, inactive labels |
-| Borders / dividers | Gray 200 | #E7EBEE | Dividers between sections |
-
-**Supported shade sets**
-- blue100 to blue900
-- gray100 to gray900
-- green100 to green900
-- orange100 to orange900
-- purple100 to purple900
-- red100 to red900
-- yellow100 to yellow900
-
-**Required**
-- Use only supported shade sets and defined color roles.
-- Pair semantic color with text or icon when the color communicates meaning.
-- Use Blue 600 only for primary interactive actions.
-- Use Purple 600 only for paid features.
-- Use blue/100 (#E8F5FF) as the active navigation background.
-- Use black text darker than gray-800 only on shades 100 to 400.
-- Use white text only on shades 500 to 900.
-- For non-yellow same-color foreground/background combinations, use only:
-  - 600 on 100
-  - 600 on 200
-  - 700 on 300
-  - 300 on 900
-  - 500 on white
-  - 500 on gray100
-- For yellow same-color foreground/background combinations, use only:
-  - 800 on 100
-  - 800 on 200
-  - 900 on 300
-  - 300 on 900
-  - 800 on white
-  - 800 on gray100
-
-**Forbidden**
-- Do not use color as decoration.
-- Do not rely on color alone to communicate meaning.
-- Do not use blue for non-interactive decoration.
-- Do not use a blue text color for active navigation items.
-- Do not use unsupported foreground/background shade combinations.
-- Do not use non-yellow same-color combinations outside the allowed set.
-- Do not use yellow same-color combinations outside the allowed yellow set.
-- Do not use yellow when another defined semantic role matches the meaning.
-
-### Typography
-
-| Role | Size | Weight | Use |
-|---|---|---|---|
-| Display | 1.5rem+ | 600 | Page titles, hero text |
-| Section heading | 0.75rem | 600 | Nav group labels, table headers |
-| Body (default) | 0.875rem | 400 | Interface copy |
-| Body medium | 0.875rem | 500 | Emphasized labels |
-| Small / caption | 0.75rem | 400 | Metadata, hints |
-
-**Required**
-- Use Geist as the typeface.
-- Import from https://cdn.f36.contentful.com.
-- Use fallback fonts -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif.
-- Use font-feature-settings: 'ss05' 1 on all Geist text.
-- Use line height 1.5 by default.
-- Use line height 1.25 only for nav items and badges.
-- Use letter spacing 0 for all sizes.
-- Use sentence case for labels.
-
-**Forbidden**
-- Do not mix more than two font weights on a single screen.
-- Do not use Title Case for labels.
-- Do not use ALL CAPS for labels.
-
-### Spacing
-
-| Token | Value | Common use |
-|---|---|---|
-| 2xs | 4px | Icon gaps, tight groupings |
-| xs | 8px | Between related items |
-| s | 12px | Component internal padding |
-| m | 16px | Standard padding |
-| l | 24px | Section padding |
-| xl | 32px | Large section gaps |
-| 2xl | 48px | Page-level separation |
-
-**Required**
-- Use only the defined spacing tokens.
-- Manage external spacing with layout wrappers: Flex, Stack, Box.
-- Use token names on layout components: spacingXs, spacingS, spacingM, etc.
-
-**Forbidden**
-- Do not use arbitrary pixel values for spacing.
-- Do not assign external spacing directly to components.
-
-### Shadows
-
-| Name | Value | Use |
-|---|---|---|
-| Default | 0 0 0 1px rgba(25,37,50,.10), 0 3px 7px -3px rgba(25,37,50,.10), 0 6px 12px -2px rgba(25,37,50,.10) | Panels, sidebar, content area |
-| Button | 0 1px 0 rgba(17,27,43,.05) | Secondary buttons |
+**Figma Make Kit:** https://www.figma.com/make/jcC82kTLl5yz6W9Mk1LJF8/Forma-36-Kit
 
-**Required**
-- Use Shadow/Default for panels, sidebar, and content area.
-- Use Shadow/Button for secondary buttons.
+**Reading order:**
+1. `guidelines/overview.md` — Design philosophy and critical rules
+2. `guidelines/composition/base-shell.md` — The app chrome you must always use
+3. `guidelines/composition/screen-patterns.md` — Pick the pattern closest to your screen
+4. `guidelines/foundations/writing.md` — Get the copy right (sentence case, verb-first labels, "Never mind")
+5. `guidelines/tokens/color.md` — Understand what each color means
+6. `guidelines/tokens/typography.md` — Type roles and the Geist setup
+7. `guidelines/tokens/spacing.md` — The spacing scale
+8. `guidelines/components/overview.md` — Skim the decision tree to pick the right components
+9. `examples/` — Start from the example closest to your screen and adapt it
 
-**Forbidden**
-- Do not create custom shadows.
-- Do not create glows.
+**Focus on:** Screen patterns, visual hierarchy, writing rules, color meaning.
+**Skim:** Individual component prop tables — reference them only when you need a specific detail.
+**Use examples as:** Starting templates to fork and adapt.
 
-### Borders & Radius
+### Path B — Developer implementing
 
-| Element | Radius |
-|---|---|
-| Panels, cards | 12px (top corners only for flush-to-edge panels) |
-| Buttons, inputs, nav items | 6px |
-| Small chips, badges | 4px |
-| Avatars | 100px (pill) |
-
-**Required**
-- Use only the defined radius values.
-- Use 12px for panels and cards.
-- Use top corners only for flush-to-edge panels.
-- Use 6px for buttons, inputs, and nav items.
-- Use 4px for small chips and badges.
-- Use 100px for avatars.
-
-**Forbidden**
-- Do not use border radius values outside 4px, 6px, 12px, and 100px.
+You are writing production code, building a Contentful app, or implementing a design spec. You need exact prop names, token values, correct import paths, and API precision.
 
----
+**Reading order:**
+1. `guidelines/overview.md` — Critical rules (memorize these)
+2. `guidelines/setup.md` — Dependencies, CSS import, font loading
+3. `guidelines/tokens/` — Read all token files. Every value you use must come from here.
+4. `guidelines/components/overview.md` — Decision tree, then read the specific component file you need
+5. `guidelines/components/<relevant-file>.md` — Full prop tables, code examples, constraints
+6. `guidelines/composition/screen-patterns.md` — Structural template for the page type you're building
+7. `guidelines/foundations/accessibility.md` — ARIA labels, focus management, contrast
+8. `examples/` — Verify your patterns match the reference implementations
 
-## Base Layout
-
-**Required**
-- Every screen uses this exact shell.
-- Do not invent alternative chrome.
-
-Figma reference: `https://www.figma.com/design/CHqkCTVTpvkqDNXtoAR5cE/Experiences-Library?node-id=6764-6490`
-
-┌──────────────────────────────────────────────────────┐
-│  Top bar  (52px, gray-100 background)                │
-├───────────────┬──────────────────────────────────────┤
-│               │  Content area                        │
-│  Sidebar      │  ┌────────────────────────────────┐  │
-│  (240px)      │  │  Header (title + actions)      │  │
-│               │  ├────────────────────────────────┤  │
-│               │  │  Page content                  │  │
-│               │  └────────────────────────────────┘  │
-└───────────────┴──────────────────────────────────────┘
-[8px agent strip]
-
-### Top bar
-
-**Required**
-- Height: `52px`.
-- Background: `gray/100`.
-- Horizontal padding: `24px` left, `64px` right.
-- The `64px` right gap is reserved for the agent strip.
-- Left content order: Contentful `"C"` logo → Space/Environment switcher pill.
-- Right content order: Search icon → Help icon → User avatar (`24px`).
-- Environment switcher background: `green/100`.
-- Environment switcher border: `green/400`.
-- Environment switcher text: `"Space > Production"` in `green/700`.
-- Environment switcher includes a `green-300` right-edge indicator strip.
-- Environment switcher includes a rocket icon.
-
-**Forbidden**
-- Do not change the top bar height.
-- Keep the top bar content order consistent with the defined structure.
-- Do not use an alternative top bar structure.
-
-### Sidebar
-
-#### Structure
-
-**Required**
-- Sidebar is present in the application shell.
-- Sidebar includes a collapse button.
-- Collapse button is a transparent `IconButton` with `CaretLeft` icon.
-- Collapse button position: bottom-right of sidebar.
-- Sidebar includes all defined sections, items, icons, and states.
-
-**Forbidden**
-- Do not stub the sidebar.
-- Do not simplify the sidebar.
-- Do not remove defined sections, items, icons, or states.
-
-#### Dimensions
-
-**Required**
-- Width: `240px`.
-- Background: `white`.
-- Shadow: `Shadow/Default`.
-- Top corners radius: `12px`.
-- Padding: `pt-12px pb-8px px-4px`.
-- Inner menu padding: `px-12px`.
-- Gap between sections: `12px`.
-- Nav item height: `32px`.
-- Nav item padding: `px-12px py-6px`.
-- Nav item gap: `8px`.
-- Nav item border radius: `4px`.
-- Section title size: `12px`.
-- Section title weight: `600`.
-- Section title color: `gray/700`.
-- Section title height: `28px`.
-- Section title left padding: `pl-12px`.
-
-#### Content
-
-**Required**
-- Sections are separated by `gray/200` bottom border.
-- Sidebar sections and items:
-  1. **Setup** — Design System *(active by default)*, Content Model
-  2. **Creation** — Experiences, Content
-  3. **Optimization** — Optimizations, Analytics
-  4. **Platform Configuration** — Collections, AI & Automations, Taxonomy, Apps
-  5. *(no title)* — Settings
-
-#### States
-
-**Required**
-- See Interaction states.
-- Nav item content: Icon (`16px`, duotone variant for active) + label (body regular, `gray/900`) + optional caret right.
-- Active state background: `blue/100` (`#E8F5FF`).
-- Default state background: transparent.
-- Hover state background: `gray/100`.
-
-#### Constraints
-
-**Required**
-- Implement the sidebar faithfully.
-- Replicate all sections, items, icons, and states exactly.
-
-**Forbidden**
-- Do not modify sidebar structure outside the defined shell.
-- Do not invent additional sidebar patterns.
-
-### Content area
-
-**Required**
-- Content area fills the remaining width.
-- Background: `white`.
-- Shadow: `Shadow/Default`.
-- Top corners radius: `12px`.
-- Padding: `pt-12px px-24px`.
-- `Header` is always present at the top of the content area.
-- Use `Title` variant for top-level pages.
-- Use `Breadcrumb` variant for subpages.
-- Page content is placed below the `Header`.
-
-**Context-dependent**
-- Set `dividerLine={true}` when the content area has a right sidebar.
-
-**Forbidden**
-- Do not omit the `Header`.
-- Do not place page content above the `Header`.
+**Focus on:** Token names, prop signatures, component rules, accessibility requirements, code conventions.
+**Skim:** Composition overview and writing guidelines — reference them for structure and copy decisions.
+**Use examples as:** API reference and correctness checks.
 
 ---
 
-## Layout rules
-
-### Layout Primitives
-
-**Required**
-- Use layout primitives to compose all layout structure outside the application shell.
-- Use only Flex, Stack, Box, and Grid for layout composition.
-- Use tokenized spacing values on layout primitives: spacingXs, spacingS, spacingM, spacingL, spacingXl, spacing2Xl.
-- Use layout primitives to control external spacing between components.
-- Keep component external spacing outside the component itself.
-- Keep layout composition inside the existing application shell defined in this document.
-
-**Preferred**
-- Use Stack for one-directional vertical grouping.
-- Use Flex for one-directional layouts that require explicit alignment, justification, or wrapping behavior.
-- Use Grid for two-dimensional layouts with rows and columns.
-- Use Box for single-region containment, padding, margin, width, or other block-level layout control.
-- Use the simplest layout primitive that satisfies the requirement.
-- Prefer Stack over Flex when only directional spacing is required.
-- Prefer Flex over Grid when the layout is one-dimensional.
-
-**Required**
-- Compose layouts from primitives first, then place defined components inside them.
-- Use nested primitives when one primitive cannot express the required structure.
-- Keep DOM order aligned with visual order.
-- Keep page-level spacing, section spacing, and inter-component spacing on layout primitives, not on child components.
-- Use existing shell regions as fixed boundaries: top bar, sidebar, content area, header, page content.
-- Keep the Header at the top of the content area.
-- Place unrestricted page content below the Header.
-
-**Context-dependent**
-- When content requires explicit columns or row/column placement, use Grid.
-- When content is arranged in a single vertical flow, use Stack.
-- When items must be aligned horizontally or distributed along one axis, use Flex.
-- When only padding, margin, width, or a single container wrapper is needed, use Box.
-- When spacing between elements is required, use spacing tokens only.
-- When a right sidebar is present in the content area, follow the existing Header rule for dividerLine={true}.
-- If a layout requirement is underspecified, use the simplest valid composition built from Box, Flex, Stack, and Grid.
-- If a named pattern is missing, compose the layout from the standard application shell and layout primitives only.
-
-**Forbidden**
-- Do not invent new layout primitives.
-- Do not invent new layout patterns outside the application shell and named patterns defined elsewhere in this document.
-- Do not use arbitrary pixel values for layout spacing.
-- Do not use components as layout substitutes when a layout primitive is sufficient.
-- Do not assign external spacing directly to components.
-- Do not use Grid for one-dimensional layouts.
-- Do not use Flex or Stack to approximate a two-dimensional grid layout.
-- Do not break the shell structure defined in Base Layout.
-- Do not reorder DOM structure to create a visual layout that changes reading or interaction order.
+## Critical rules
 
----
+These apply to both paths. Do not override them.
 
-## Component rules
-
-### Buttons
-
-**Required**
-- Use `Button` for button actions.
-- Use `Primary` for the single most important action in a context. Maximum: one per context.
-- Use `Secondary` for supporting actions.
-- Use `Positive` for constructive actions: create, publish, add.
-- Use `Negative` for destructive or irreversible actions: delete, remove, archive.
-- Use `Transparent` only on light backgrounds.
-- Use native button semantics for button actions.
-- Icon-only actions must use `IconButton` or `ToggleButton` with a descriptive `aria-label`.
-- Button groups must expose an `aria-label`.
-
-**Context-dependent**
-- Use `small` for toolbars.
-- Use `medium` as the default size.
-- Use `large` only for hero CTAs.
-- If a button is marked disabled through a custom button element or `role=button`, click and keydown handlers must not fire.
-- For state behavior, see **Interaction states**.
-- For loading behavior, see **Interaction & State rules**.
-
-**Forbidden**
-- Do not use more than one `Primary` button in the same context.
-
-### Forms
-
-**Required**
-- Every input must live inside a `FormControl`.
-- Structure is always: `Label → Input → Help text → Validation message`.
-- `FormControl.Label` is required.
-- `FormControl.HelpText` is for guidance that always shows.
-- Pass `isRequired`, `isInvalid`, and `isDisabled` to `FormControl`, not to the input directly.
-- Required form elements must be marked programmatically with `isRequired`, not only visually.
-- Help text and validation messages must stay inside the same `FormControl`.
-- `TextInput` and `Textarea` with separate labels must expose `id` for `htmlFor`.
-- Controls used in form submission must expose `name` when submission depends on it.
-- Choose the input type as follows:
-  - Short free text → `TextInput`
-  - Long free text → `Textarea`
-  - Pick one from a short list (`≤8` options) → `Select`
-  - Pick one from a long list → `Autocomplete`
-  - Toggle one option → `Checkbox`
-  - Pick one from a mutually exclusive group → `Radio.Group`
-
-**Context-dependent**
-- `FormControl.ValidationMessage` is for errors and appears only when invalid. See **Feedback selection rules**.
-- If there is no visible label, provide `aria-label` or `aria-labelledby` as supported by the control.
-- Use `Checkbox.Group` or an equivalent fieldset/legend structure for related checkbox options.
-- Use `Radio.Group` to group related radio buttons and provide a group label.
-- If a visible legend is not possible for checkbox or radio groups, use `aria-labelledby`.
-- `Switch` labels must describe the action being controlled.
-- If a visible label is not present for `Select`, provide `aria-label`.
-- Use `Datepicker` inside `FormControl` when label, help text, or validation is needed.
-- Icon-only `Datepicker` trigger buttons must provide a screen-reader label.
-- Disabled or invalid date states must be communicated in text, not only visually.
-- In `Multiselect`, if a visible label is not present, provide an `aria-label`.
-- For state behavior, see **Interaction states**.
-
-**Forbidden**
-- Do not use placeholder text as a replacement for a label.
-
-### Feedback & Status
-
-**Required**
-- Use `Notification` for immediate feedback after a user action.
-- `Notification` dismisses after 6 seconds.
-- `Notification.success('Entry published')` uses active voice and present tense.
-- `Notification.error(...)` must be specific and actionable.
-- Use `Note` for proactive context the user needs before acting.
-- Place `Note` near the relevant content, not at the top of the page generically.
-- Badge labels and status indicators stay to one word.
-- Use `EntityStatusBadge` for Contentful entity status.
-
-**Context-dependent**
-- `Note` variants: neutral, primary, positive, warning, negative, premium.
-- Badge status mapping:
-  - positive = Published
-  - warning = Draft
-  - negative = Deleted
-- For selection logic, see **Feedback selection rules**.
-
-**Forbidden**
-- Do not use `Notification` for persistent context.
-- Do not construct a raw `Badge` for Contentful entity status.
-
-### Navigation & Overlays
-
-**Required**
-- For `Modal` usage, see **Feedback selection rules**.
-- `Modal` content must include a clear title and description.
-- Use `Menu` for actions and navigation choices triggered by a button.
-- `Tabs` navigate between sections of related content.
-- Maximum tabs: `6`.
-- Tab labels must accurately describe the panel content.
-- Provide a unique `panelId` for each tab-panel relationship.
-- `Tooltip` is supplementary, non-critical context.
-- Tooltip content must be short.
-- Always include a unique `id` prop on `Tooltip`.
-- If the trigger is icon-only, the trigger must have its own accessible label independent of the tooltip text.
-
-**Context-dependent**
-- Focus moves into the modal when it opens.
-- Focus remains trapped inside the modal while it is open.
-- Focus returns to the invoking control when the modal closes.
-- Modal dialogs close with `Escape` and outside click unless disabled.
-- Menus move focus into the menu when they open and support keyboard navigation among items.
-- For state behavior, see **Interaction states**.
-
-**Forbidden**
-- Do not use `Select` for actions.
-- Do not put links, buttons, or forms inside a `Tooltip`.
+- **Tokens only** — never hardcode hex colors, pixel values, or font stacks. Always use `@contentful/f36-tokens`.
+- **Sentence case** — all labels, headings, buttons, menu items. Never Title Case or ALL CAPS.
+- **One primary button** per screen section maximum.
+- **Every input in a `FormControl`** — Label is required for accessibility.
+- **Every page has a `Header`** — Title variant for top-level, Breadcrumb for subpages.
+- **Color carries meaning** — never decorative. Always pair with text or icon.
+- **Phosphor icons only** — never Material, Heroicons, Feather, or Lucide.
+- **"Never mind"** — the cancel label for destructive confirmations. Not "Cancel".
+- **`Layout` not `Workbench`** — Workbench is deprecated.
+- **No custom shadows** — only `shadowDefault`, `shadowHeavy`, `shadowButton`, `insetBoxShadowDefault`.
+- **No border radius outside the scale** — 4px, 6px, 12px, 100px only.
 
 ---
 
-## Interaction & State rules
-
-This section defines behavior and interaction rules. Use it with **Component rules**, **Interaction states**, and **Feedback selection rules**. Do not restate component selection or structural rules here.
-
-### Sidebar
-
-**Required**
-- Sidebar navigation uses the global **Interaction states** model.
-- The active item is `Design System` by default.
-- The collapse control is an `IconButton` with `CaretLeft`.
-
-**Context-dependent**
-- Active nav items use `blue/100` (`#E8F5FF`) background fill.
-- Default nav items use transparent background.
-- Hovered nav items use `gray/100` background fill.
-- Active nav items use the duotone icon variant.
-
-### Content area
-
-**Required**
-- See **Base Layout**.
-
-### Buttons
-
-**Required**
-- Buttons use the global **Interaction states** model.
-- Loading uses `isLoading`.
-
-**Forbidden**
-- Do not disable a button and add a spinner manually.
+## Code conventions
 
-### Forms
+From the [Forma 36 code style guide](https://github.com/contentful/forma-36/blob/main/docs/code-style-guide.md):
 
-**Required**
-- Forms use the global **Interaction states** model.
-
-### Feedback & Status
-
-**Required**
-- See **Feedback selection rules**.
-
-### Navigation & Overlays
-
-**Required**
-- `Modal` behavior follows the global **Interaction states** model.
-- Menus support keyboard navigation among items.
-- Tooltips are non-critical and supplementary.
-
-**Context-dependent**
-- Focus moves into the menu when it opens.
-- Focus moves into the modal when it opens.
-- Focus remains trapped inside the modal while it is open.
-- Focus returns to the invoking control when the modal closes.
-- Modal closes with `Escape` and outside click unless disabled.
-
-### Keyboard and focus
-
-**Required**
-- All interactive elements are keyboard operable.
-- Tab order follows the rendered interaction order.
-
-### Semantic structure and state communication
-
-**Required**
-- Semantic DOM order matches visual order.
-
-### Header and layout accessibility
-
-**Required**
-- Breadcrumbs and back buttons have descriptive accessible labels.
-- Interactive elements placed in header actions or filters are keyboard accessible and clearly labeled.
-- Interactive content placed inside layout containers preserves keyboard navigation and focus management.
-
-**Context-dependent**
-- If multiple headers are present, use the `as` prop to avoid duplicate landmarks and preserve heading hierarchy.
+- Prefix boolean props with `is` (e.g. `isActive`, `isDisabled`, `isLoading`)
+- Prefix show/hide props with `with` (e.g. `withDragHandle`, `withCloseButton`)
+- Callback props use `on` prefix (`onClick`, `onChange`); handler functions use `handle` (`handleClick`)
+- Component type names use `ComponentNameProps` pattern
+- Use `camelCase` for all prop names
+- Pass string prop values with double quotes directly, not wrapped in `{}`
+- Prefer `className` over inline `style` unless manipulating dynamic values
 
 ---
 
-## Feedback selection rules
-
-### Selection logic
-
-**Required**
-- Use FormControl.ValidationMessage when the message describes an error on a specific input.
-- Use Note when the message must remain visible while the user reviews or acts on related content.
-- Use Notification when the message confirms the result of a user action and can dismiss after 6 seconds.
-- Use Modal when the user must confirm before proceeding or when the information is essential to the current workflow.
+## Dependencies
 
-### FormControl.ValidationMessage
+```bash
+npm install @contentful/f36-components @contentful/f36-tokens @contentful/f36-icons
+```
 
-**Use when**
+Requires React 18. Compatible with Vite. CSS import is mandatory:
 
-**Context-dependent**
-- the message is tied to a specific field
-- the field is invalid
+```tsx
+import '@contentful/f36-components/dist/styles.css';
+```
 
-**Do not use when**
-
-**Forbidden**
-- the message applies to the page, section, or workflow rather than a specific input
-- the message is only informational guidance
-
-### Note
-
-**Use when**
-
-**Context-dependent**
-- the message is proactive context the user needs before acting
-- the message must remain visible
-- the message belongs near the relevant content
-
-**Do not use when**
-
-**Forbidden**
-- the message is a field-specific validation error
-- the message is only a temporary action result
-- the message is placed at the top of the page generically
-
-### Notification
-
-**Use when**
-
-**Context-dependent**
-- the message is immediate feedback after a user action
-- the message can dismiss after 6 seconds
-- the message is an action result such as success or error
-
-**Do not use when**
-
-**Forbidden**
-- the message must remain visible while the user works
-- the message is persistent context
-- the message replaces inline validation for a specific field
-
-### Modal
-
-**Use when**
-
-**Context-dependent**
-- the user must confirm before proceeding
-- the information is essential to the current workflow
-- the interaction blocks the interface
-
-**Do not use when**
-
-**Forbidden**
-- the information is non-essential
-- the interaction interrupts high-stakes flows without confirmation need
-- the message is only a transient action result
-- the message is only persistent inline context
-
-### Forbidden patterns
-
-**Forbidden**
-- Do not use Notification for persistent context
-- Do not use Note for field validation
-- Do not use Modal for non-essential information
-- Do not use Modal for a transient success or error message
-- Do not use FormControl.ValidationMessage for page-level or section-level messaging
-
-### Acceptance criteria
-
-**Required**
-- A field-specific error uses FormControl.ValidationMessage
-- A message that must remain visible uses Note
-- A temporary action result uses Notification
-- A blocking confirmation uses Modal
-- Notification messages dismiss after 6 seconds
-- Note is placed near the relevant content
-- FormControl.ValidationMessage appears only when invalid
-- Modal is used only for confirmation before proceeding or information essential to the current workflow
+Font: Geist from `https://cdn.f36.contentful.com`. Apply `font-feature-settings: 'ss05' 1`.
 
 ---
 
-## Content & writing
+## File map
 
-### Writing rules
+Each folder contains an `overview.md` that indexes its contents.
 
-**Required**
-- Use active voice.
-- Use present tense.
-- Use sentence case everywhere.
-- Start button labels with a verb.
-- Start link labels with a verb when the link is an action.
-- Error messages must state what went wrong and what to do next.
-- Confirmation dialogs for destructive actions must state exactly what will be destroyed.
+### `guidelines/`
 
-**Forbidden**
-- Do not use "please".
-- Do not use "click here".
-- Do not use "learn more" without context.
-- Do not use vague single-word labels such as "Go" or "Submit".
-- Do not use Title Case.
-- Do not use ALL CAPS.
+| File | What it covers |
+|---|---|
+| `overview.md` | Design philosophy, product character, critical rules |
+| `setup.md` | Dependencies, CSS import, Geist font, token imports, icon library |
 
-**Context-dependent**
-- If a link is navigation rather than an action, the label must describe the destination clearly.
+### `guidelines/tokens/`
 
-### Button writing rules
+| File | What it covers |
+|---|---|
+| `overview.md` | Token philosophy and index |
+| `color.md` | Semantic colors, gray scale, blue/green/red/orange/purple/yellow palettes |
+| `typography.md` | Font families, sizes, weights, line heights, letter spacing, composite type roles |
+| `spacing.md` | 4px–80px spacing scale, content width tokens |
+| `effects.md` | Shadows (4 only), focus rings, border radius, z-index, transitions |
 
-**Required**
-- Button labels start with a verb.
-- Maximum button label length: 3 words.
-- The dismiss action for a destructive flow uses Never mind.
+### `guidelines/components/`
 
-**Forbidden**
-- Do not use Cancel as the dismiss action for a destructive flow.
+| File | What it covers |
+|---|---|
+| `overview.md` | Component decision tree and file index |
+| `layout.md` | `Box`, `Flex`, `Stack`, `Grid`, `Layout` |
+| `buttons.md` | `Button` (5 variants), `IconButton`, `TextLink`, `CopyButton` |
+| `forms.md` | `FormControl`, `TextInput`, `Textarea`, `Select`, `Autocomplete`, `Multiselect`, `Checkbox`, `Radio`, `Switch`, `DatePicker` |
+| `feedback.md` | `Notification`, `Note`, `Badge`, `EntityStatusBadge`, `Spinner` |
+| `navigation.md` | `Tabs`, `Modal`, `Menu`, `Tooltip`, `Popover`, `NavList` |
+| `data-display.md` | `Table`, `Card`, `EntityList`, `Accordion`, `Collapse`, `Skeleton`, `Pagination`, `List`, `ProgressStepper` |
+| `content-media.md` | `Asset`, `Avatar`, `Image`, `DateTime`, `UsageCard` |
+| `utility.md` | Typography components, `Header`, `DragHandle`, `Pill`, Icons |
+
+### `guidelines/composition/`
+
+| File | What it covers |
+|---|---|
+| `overview.md` | Composition philosophy and file index |
+| `base-shell.md` | Standard app chrome — top bar (52px), sidebar (240px), content area |
+| `screen-patterns.md` | 9 named patterns: list, detail, settings, empty state, error, confirmation, wizard, dashboard, form |
 
-### Modal writing rules
+### `guidelines/foundations/`
 
-**Required**
-- Modal title format: verb + noun.
-- Confirm button format: verb + noun.
-- Destructive confirmation copy states exactly what will be destroyed.
-- The dismiss action for a destructive flow uses Never mind.
+| File | What it covers |
+|---|---|
+| `overview.md` | Foundations index |
+| `writing.md` | Voice & tone, sentence case, button labels, error messages, forbidden phrases, status labels |
+| `icons.md` | Phosphor library, Regular vs Duotone, sizing (14/16/20px), color-by-role |
+| `accessibility.md` | WCAG contrast, keyboard navigation, ARIA labels, screen reader guidance, focus rings |
 
-**Forbidden**
-- Do not use a vague modal title.
-- Do not use a vague confirm label.
-- Do not use Cancel as the dismiss action for a destructive flow.
+### `examples/`
 
----
+Working TSX files demonstrating correct usage. Each maps to a screen pattern.
 
-## What Forma 36 Never Does
-
-**Forbidden**
-- Do not use decorative color.
-- Do not create custom shadows or glows.
-- Do not use rounded corners outside 4px, 6px, 12px, and 100px.
-- Do not use arbitrary spacing.
-- Do not use Title Case labels.
-- Do not use more than one primary button per screen section.
-- Do not use Button as a link. Use TextLink for navigation.
-- Do not use a bare Badge for entity status. Use EntityStatusBadge.
-- Do not use Notification for persistent context. Use Note and follow **Feedback selection rules**.
-- Do not place interactive elements inside Tooltip content.
-- Do not omit the Header from a page.
-- Do not use Workbench. Use Layout.
-- Do not use raw hex colors in code. Use tokens from @contentful/f36-tokens.
+| File | Pattern | What it shows |
+|---|---|---|
+| `list-page.tsx` | List / Index | Table, search, EntityStatusBadge, Menu actions, Pagination, empty state, Skeleton |
+| `detail-page.tsx` | Detail / Edit | Right sidebar, breadcrumbs, form validation, unsaved-changes Note |
+| `settings-page.tsx` | Settings | Grouped sections, Switch toggles, danger zone |
+| `confirmation-dialog.tsx` | Confirmation | Modal, "Never mind" cancel, `isLoading` confirm, `shouldCloseOnOverlayClick={false}` |
+| `form-page.tsx` | Standalone Form | `Layout variant="narrow"`, grouped FormControls, Accordion, Notification |
+| `error-state.tsx` | Error State | Centered error, WarningOctagonIcon, "Try again" + "Go back" |
diff --git a/skills/examples/confirmation-dialog.tsx b/skills/examples/confirmation-dialog.tsx
new file mode 100644
index 0000000000..24f1f3a5cf
--- /dev/null
+++ b/skills/examples/confirmation-dialog.tsx
@@ -0,0 +1,50 @@
+/**
+ * Confirmation Dialog — destructive action pattern.
+ * Title and confirm button always match. Cancel is "Never mind".
+ */
+import { Modal, Button, Paragraph } from '@contentful/f36-components';
+import { useState } from 'react';
+
+function DeleteContentTypeDialog() {
+  const [isOpen, setIsOpen] = useState(false);
+  const [isDeleting, setIsDeleting] = useState(false);
+
+  async function handleDelete() {
+    setIsDeleting(true);
+    // ... perform deletion
+    setIsDeleting(false);
+    setIsOpen(false);
+  }
+
+  return (
+    <>
+      <Button variant="negative" onClick={() => setIsOpen(true)}>
+        Delete content type
+      </Button>
+
+      <Modal
+        isShown={isOpen}
+        onClose={() => setIsOpen(false)}
+        size="small"
+        shouldCloseOnOverlayClick={false}
+      >
+        <Modal.Header title="Delete content type" onClose={() => setIsOpen(false)} />
+        <Modal.Content>
+          <Paragraph>
+            This content type and all its fields will be permanently deleted. This cannot be undone.
+          </Paragraph>
+        </Modal.Content>
+        <Modal.Controls>
+          <Button variant="secondary" onClick={() => setIsOpen(false)}>
+            Never mind
+          </Button>
+          <Button variant="negative" isLoading={isDeleting} onClick={handleDelete}>
+            Delete content type
+          </Button>
+        </Modal.Controls>
+      </Modal>
+    </>
+  );
+}
+
+export { DeleteContentTypeDialog };
diff --git a/skills/examples/detail-page.tsx b/skills/examples/detail-page.tsx
new file mode 100644
index 0000000000..8e9e44923b
--- /dev/null
+++ b/skills/examples/detail-page.tsx
@@ -0,0 +1,84 @@
+/**
+ * Detail / Edit Page — single entity view with right sidebar.
+ */
+import {
+  Layout,
+  Header,
+  Button,
+  Stack,
+  FormControl,
+  TextInput,
+  Textarea,
+  EntityStatusBadge,
+  Note,
+  Paragraph,
+  SectionHeading,
+  Box,
+} from '@contentful/f36-components';
+
+function EntryDetailPage() {
+  return (
+    <Layout
+      variant="wide"
+      header={
+        <Layout.Header>
+          <Header
+            title="Homepage banner"
+            breadcrumbs={[{ label: 'Content', href: '/content' }]}
+            withBackButton
+            dividerLine
+            actions={
+              <Stack spacing="spacingS">
+                <Button variant="secondary">Save</Button>
+                <Button variant="positive">Publish</Button>
+              </Stack>
+            }
+          />
+        </Layout.Header>
+      }
+      rightSidebar={
+        <Layout.Sidebar>
+          <Stack flexDirection="column" spacing="spacingM" padding="spacingM">
+            <SectionHeading>Status</SectionHeading>
+            <EntityStatusBadge entityStatus="draft" />
+
+            <SectionHeading marginTop="spacingL">Metadata</SectionHeading>
+            <Paragraph>Created: Jan 15, 2025</Paragraph>
+            <Paragraph>Updated: 2 hours ago</Paragraph>
+          </Stack>
+        </Layout.Sidebar>
+      }
+    >
+      <Layout.Body>
+        <Note variant="warning" marginBottom="spacingL">
+          You have unsaved changes that will be lost if you navigate away.
+        </Note>
+
+        <Stack flexDirection="column" spacing="spacingM">
+          <FormControl isRequired>
+            <FormControl.Label>Title</FormControl.Label>
+            <TextInput defaultValue="Homepage banner" />
+          </FormControl>
+
+          <FormControl>
+            <FormControl.Label>Description</FormControl.Label>
+            <Textarea rows={4} defaultValue="Main promotional banner for the homepage." />
+            <FormControl.HelpText>
+              A short description displayed below the banner title.
+            </FormControl.HelpText>
+          </FormControl>
+
+          <FormControl isRequired isInvalid>
+            <FormControl.Label>Slug</FormControl.Label>
+            <TextInput defaultValue="" />
+            <FormControl.ValidationMessage>
+              This field is required. Add a value before publishing.
+            </FormControl.ValidationMessage>
+          </FormControl>
+        </Stack>
+      </Layout.Body>
+    </Layout>
+  );
+}
+
+export { EntryDetailPage };
diff --git a/skills/examples/error-state.tsx b/skills/examples/error-state.tsx
new file mode 100644
index 0000000000..060a741f94
--- /dev/null
+++ b/skills/examples/error-state.tsx
@@ -0,0 +1,37 @@
+/**
+ * Error State — full-page error with recovery action.
+ */
+import { Flex, Heading, Paragraph, Button, Stack } from '@contentful/f36-components';
+import { WarningOctagonIcon } from '@contentful/f36-icons';
+import tokens from '@contentful/f36-tokens';
+
+function PageError({ section = 'content types' }: { section?: string }) {
+  return (
+    <Flex
+      flexDirection="column"
+      alignItems="center"
+      justifyContent="center"
+      padding="spacing2Xl"
+      style={{ minHeight: '400px' }}
+    >
+      <WarningOctagonIcon
+        size="medium"
+        style={{ width: '48px', height: '48px', color: tokens.red600, marginBottom: tokens.spacingM }}
+      />
+      <Heading marginBottom="spacingXs">Couldn't load {section}</Heading>
+      <Paragraph marginBottom="spacingL">
+        Something went wrong while loading this page. Check your connection and try again.
+      </Paragraph>
+      <Stack spacing="spacingS">
+        <Button variant="primary" onClick={() => window.location.reload()}>
+          Try again
+        </Button>
+        <Button variant="secondary" onClick={() => window.history.back()}>
+          Go back
+        </Button>
+      </Stack>
+    </Flex>
+  );
+}
+
+export { PageError };
diff --git a/skills/examples/form-page.tsx b/skills/examples/form-page.tsx
new file mode 100644
index 0000000000..0b9e1e6dcb
--- /dev/null
+++ b/skills/examples/form-page.tsx
@@ -0,0 +1,108 @@
+/**
+ * Standalone Form Page — narrow layout, grouped fields, inline validation.
+ */
+import {
+  Layout,
+  Header,
+  Button,
+  Stack,
+  FormControl,
+  TextInput,
+  Textarea,
+  Select,
+  Checkbox,
+  Heading,
+  Note,
+  Accordion,
+  Notification,
+} from '@contentful/f36-components';
+
+function CreateContentTypePage() {
+  function handleSave() {
+    Notification.success('Content type created');
+  }
+
+  return (
+    <Layout
+      variant="narrow"
+      header={
+        <Layout.Header>
+          <Header
+            title="Create content type"
+            breadcrumbs={[{ label: 'Content model', href: '/content-model' }]}
+            withBackButton
+            actions={
+              <Stack spacing="spacingS">
+                <Button variant="secondary">Never mind</Button>
+                <Button variant="primary" onClick={handleSave}>
+                  Create
+                </Button>
+              </Stack>
+            }
+          />
+        </Layout.Header>
+      }
+    >
+      <Layout.Body>
+        <Stack flexDirection="column" spacing="spacingXl">
+          {/* Basic info */}
+          <Stack flexDirection="column" spacing="spacingM">
+            <Heading>Basic information</Heading>
+
+            <FormControl isRequired>
+              <FormControl.Label>Name</FormControl.Label>
+              <TextInput placeholder="e.g. Blog Post" />
+              <FormControl.HelpText>
+                The display name for this content type.
+              </FormControl.HelpText>
+            </FormControl>
+
+            <FormControl isRequired>
+              <FormControl.Label>API identifier</FormControl.Label>
+              <TextInput placeholder="e.g. blogPost" />
+              <FormControl.HelpText>
+                Used in API responses and SDK queries. Cannot be changed later.
+              </FormControl.HelpText>
+            </FormControl>
+
+            <FormControl>
+              <FormControl.Label>Description</FormControl.Label>
+              <Textarea rows={3} placeholder="Describe what this content type is for" />
+            </FormControl>
+          </Stack>
+
+          {/* Display settings */}
+          <Stack flexDirection="column" spacing="spacingM">
+            <Heading>Display</Heading>
+
+            <FormControl>
+              <FormControl.Label>Entry title field</FormControl.Label>
+              <Select defaultValue="title">
+                <Select.Option value="title">Title</Select.Option>
+                <Select.Option value="name">Name</Select.Option>
+              </Select>
+              <FormControl.HelpText>
+                The field used as the entry title in lists and references.
+              </FormControl.HelpText>
+            </FormControl>
+          </Stack>
+
+          {/* Advanced — collapsed by default */}
+          <Accordion>
+            <Accordion.Item title="Advanced settings">
+              <Stack flexDirection="column" spacing="spacingM">
+                <Note variant="neutral">
+                  These settings are optional and can be changed later.
+                </Note>
+                <Checkbox>Enable localization for all fields</Checkbox>
+                <Checkbox>Enable real-time collaboration</Checkbox>
+              </Stack>
+            </Accordion.Item>
+          </Accordion>
+        </Stack>
+      </Layout.Body>
+    </Layout>
+  );
+}
+
+export { CreateContentTypePage };
diff --git a/skills/examples/list-page.tsx b/skills/examples/list-page.tsx
new file mode 100644
index 0000000000..ceccbcadc0
--- /dev/null
+++ b/skills/examples/list-page.tsx
@@ -0,0 +1,146 @@
+/**
+ * List / Index Page — the most common Contentful screen pattern.
+ * Shows a filterable, paginated table of content types.
+ */
+import {
+  Layout,
+  Header,
+  Button,
+  Table,
+  TextInput,
+  EntityStatusBadge,
+  Menu,
+  IconButton,
+  Pagination,
+  Stack,
+  Flex,
+  Paragraph,
+  Heading,
+  Skeleton,
+} from '@contentful/f36-components';
+import { PlusIcon, SearchIcon, MoreHorizontalIcon } from '@contentful/f36-icons';
+
+function ContentTypesListPage() {
+  return (
+    <Layout
+      variant="wide"
+      header={
+        <Layout.Header>
+          <Header
+            title="Content types"
+            actions={
+              <Button variant="primary" startIcon={<PlusIcon />}>
+                Add content type
+              </Button>
+            }
+            filters={
+              <TextInput
+                type="search"
+                placeholder="Search content types"
+                icon={<SearchIcon />}
+              />
+            }
+          />
+        </Layout.Header>
+      }
+    >
+      <Layout.Body>
+        <Table>
+          <Table.Head>
+            <Table.Row>
+              <Table.Cell>Name</Table.Cell>
+              <Table.Cell>Fields</Table.Cell>
+              <Table.Cell>Updated</Table.Cell>
+              <Table.Cell>Status</Table.Cell>
+              <Table.Cell width="60px" />
+            </Table.Row>
+          </Table.Head>
+          <Table.Body>
+            <Table.Row>
+              <Table.Cell>Blog Post</Table.Cell>
+              <Table.Cell>12</Table.Cell>
+              <Table.Cell>2 hours ago</Table.Cell>
+              <Table.Cell>
+                <EntityStatusBadge entityStatus="published" />
+              </Table.Cell>
+              <Table.Cell>
+                <Menu>
+                  <Menu.Trigger>
+                    <IconButton
+                      icon={<MoreHorizontalIcon />}
+                      aria-label="Actions"
+                      variant="transparent"
+                      size="small"
+                    />
+                  </Menu.Trigger>
+                  <Menu.List>
+                    <Menu.Item>Edit</Menu.Item>
+                    <Menu.Item>Duplicate</Menu.Item>
+                    <Menu.Divider />
+                    <Menu.Item>Delete</Menu.Item>
+                  </Menu.List>
+                </Menu>
+              </Table.Cell>
+            </Table.Row>
+          </Table.Body>
+        </Table>
+
+        <Flex justifyContent="center" marginTop="spacingL">
+          <Pagination
+            activePage={1}
+            onPageChange={() => {}}
+            totalItems={50}
+            itemsPerPage={20}
+          />
+        </Flex>
+      </Layout.Body>
+    </Layout>
+  );
+}
+
+/**
+ * Empty state variant — shown when no content types exist yet.
+ */
+function ContentTypesEmptyState() {
+  return (
+    <Flex
+      flexDirection="column"
+      alignItems="center"
+      justifyContent="center"
+      padding="spacing2Xl"
+      style={{ minHeight: '400px' }}
+    >
+      <Heading marginBottom="spacingS">No content types yet</Heading>
+      <Paragraph marginBottom="spacingL">
+        Content types define the structure of your content. Start by adding your first one.
+      </Paragraph>
+      <Button variant="primary" startIcon={<PlusIcon />}>
+        Add content type
+      </Button>
+    </Flex>
+  );
+}
+
+/**
+ * Loading state — shown while data is being fetched.
+ */
+function ContentTypesLoading() {
+  return (
+    <Table>
+      <Table.Head>
+        <Table.Row>
+          <Table.Cell>Name</Table.Cell>
+          <Table.Cell>Fields</Table.Cell>
+          <Table.Cell>Updated</Table.Cell>
+          <Table.Cell>Status</Table.Cell>
+          <Table.Cell width="60px" />
+        </Table.Row>
+      </Table.Head>
+      <Table.Body>
+        <Skeleton.Row rowCount={5} columnCount={5} />
+      </Table.Body>
+    </Table>
+  );
+}
+
+export { ContentTypesListPage, ContentTypesEmptyState, ContentTypesLoading };
diff --git a/skills/examples/settings-page.tsx b/skills/examples/settings-page.tsx
new file mode 100644
index 0000000000..0aa8a3c9ba
--- /dev/null
+++ b/skills/examples/settings-page.tsx
@@ -0,0 +1,84 @@
+/**
+ * Settings Page — feature configuration with danger zone.
+ */
+import {
+  Layout,
+  Header,
+  Button,
+  Stack,
+  FormControl,
+  TextInput,
+  Switch,
+  Select,
+  Heading,
+  Note,
+  Box,
+} from '@contentful/f36-components';
+import tokens from '@contentful/f36-tokens';
+
+function WebhookSettingsPage() {
+  return (
+    <Layout
+      variant="narrow"
+      header={
+        <Layout.Header>
+          <Header
+            title="Webhook settings"
+            actions={<Button variant="primary">Save changes</Button>}
+          />
+        </Layout.Header>
+      }
+    >
+      <Layout.Body>
+        <Stack flexDirection="column" spacing="spacingXl">
+          {/* General section */}
+          <Box>
+            <Heading marginBottom="spacingM">General</Heading>
+            <Stack flexDirection="column" spacing="spacingM">
+              <FormControl isRequired>
+                <FormControl.Label>Webhook name</FormControl.Label>
+                <TextInput defaultValue="Deploy to production" />
+              </FormControl>
+
+              <FormControl isRequired>
+                <FormControl.Label>URL</FormControl.Label>
+                <TextInput type="url" defaultValue="https://api.example.com/webhook" />
+                <FormControl.HelpText>
+                  The endpoint that receives the webhook payload.
+                </FormControl.HelpText>
+              </FormControl>
+
+              <FormControl>
+                <FormControl.Label>Content type</FormControl.Label>
+                <Select defaultValue="json">
+                  <Select.Option value="json">application/json</Select.Option>
+                  <Select.Option value="form">application/x-www-form-urlencoded</Select.Option>
+                </Select>
+              </FormControl>
+            </Stack>
+          </Box>
+
+          {/* Triggers section */}
+          <Box>
+            <Heading marginBottom="spacingM">Triggers</Heading>
+            <Stack flexDirection="column" spacing="spacingM">
+              <Switch defaultChecked>Trigger on publish</Switch>
+              <Switch defaultChecked>Trigger on unpublish</Switch>
+              <Switch>Trigger on delete</Switch>
+            </Stack>
+          </Box>
+
+          {/* Danger zone */}
+          <Box style={{ borderTop: `1px solid ${tokens.gray200}`, paddingTop: tokens.spacingXl }}>
+            <Note variant="negative" title="Danger zone" marginBottom="spacingM">
+              Deleting this webhook is permanent and cannot be undone.
+            </Note>
+            <Button variant="negative">Delete webhook</Button>
+          </Box>
+        </Stack>
+      </Layout.Body>
+    </Layout>
+  );
+}
+
+export { WebhookSettingsPage };
diff --git a/skills/guidelines/components/buttons.md b/skills/guidelines/components/buttons.md
new file mode 100644
index 0000000000..16b2884c59
--- /dev/null
+++ b/skills/guidelines/components/buttons.md
@@ -0,0 +1,87 @@
+# Buttons
+
+## Button
+
+Four variants with clear hierarchy:
+
+| Variant | Color | Use | Limit |
+|---|---|---|---|
+| `primary` | Blue | The single most important action | **One per screen section** |
+| `secondary` | Gray outline | Supporting actions | Default choice |
+| `positive` | Green | Constructive: create, publish, add | |
+| `negative` | Red | Destructive: delete, remove, archive | |
+| `transparent` | None | Lowest priority; light backgrounds only | |
+
+**Sizes:** `small` (toolbars), `medium` (default), `large` (rare, hero CTAs only)
+
+```tsx
+<Button variant="primary" startIcon={<PlusIcon />}>Add field</Button>
+<Button variant="secondary">Export</Button>
+<Button variant="positive">Publish</Button>
+<Button variant="negative">Delete entry</Button>
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `variant` | `'primary'` `'secondary'` `'positive'` `'negative'` `'transparent'` | |
+| `size` | `'small'` `'medium'` `'large'` | |
+| `startIcon` / `endIcon` | ReactNode | Icon element |
+| `isDisabled` | boolean | |
+| `isLoading` | boolean | Shows spinner — never disable + add spinner manually |
+| `isFullWidth` | boolean | |
+| `as` | ElementType | Use `as="a"` with `href` for navigation buttons |
+
+**Writing rules:**
+- Always start with a verb: "Add field", "Delete entry", "Publish"
+- Max 3 words
+- Sentence case
+- Cancel for destructive actions: **"Never mind"** — not "Cancel"
+
+## IconButton
+
+Icon-only button with built-in tooltip from `aria-label`.
+
+```tsx
+<IconButton icon={<MoreHorizontalIcon />} variant="secondary" aria-label="More actions" />
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `icon` | ReactNode | Required |
+| `variant` | Same as Button | |
+| `aria-label` | string | Required — doubles as tooltip |
+| `size` | Same as Button | |
+
+Do not use IconButton for navigation.
+
+## TextLink
+
+For navigation and low-priority actions. Never use Button for navigation.
+
+```tsx
+<TextLink href="/settings">Settings</TextLink>
+<TextLink as="button" onClick={handleClear}>Clear filters</TextLink>
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `as` | `'a'` (default) or `'button'` | `a` = navigation, `button` = action |
+| `variant` | `'primary'` `'positive'` `'negative'` `'secondary'` `'muted'` `'white'` `'premium'` | |
+| `icon` | ReactNode | |
+| `alignIcon` | `'start'` `'end'` | |
+
+Use `rel="noreferrer noopener"` with `target="_blank"`.
+
+## CopyButton
+
+Place at the end of content the user wants to copy.
+
+```tsx
+<CopyButton value="abc123" tooltipText="Copy ID" />
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `value` | string | Required — the text to copy |
+| `tooltipText` | string | Default: "Copy to clipboard" |
+| `tooltipCopiedText` | string | Default: "Copied!" |
diff --git a/skills/guidelines/components/content-media.md b/skills/guidelines/components/content-media.md
new file mode 100644
index 0000000000..18922f902e
--- /dev/null
+++ b/skills/guidelines/components/content-media.md
@@ -0,0 +1,65 @@
+# Content & Media
+
+## Asset
+
+Represents an asset visually without displaying the file itself.
+
+```tsx
+<Asset src="/preview.jpg" type="image" title="Banner image" status="published" />
+```
+
+Types: `image`, `pdf`, `video`, `audio`, `code`, `spreadsheet`. When `type="image"` renders `<img>`. Archived assets show an icon.
+
+## Avatar
+
+```tsx
+<Avatar src="/user.jpg" size="medium" variant="user" />
+<Avatar initials="JD" size="small" colorVariant="purple" />
+```
+
+| Prop | Values |
+|---|---|
+| `size` | `'tiny'` (20px) `'small'` (24px) `'medium'` (32px) `'large'` (48px) |
+| `variant` | `'user'` `'app'` |
+| `colorVariant` | `'gray'` `'green'` `'purple'` `'pink'` `'muted'` |
+| `src` | Image URL |
+| `initials` | Fallback text |
+
+Pass meaningful `alt` when used without adjacent name text.
+
+## Image
+
+Basic image component.
+
+```tsx
+<Image src="/photo.jpg" alt="Product screenshot" />
+```
+
+## DateTime
+
+Display-only date/time. Renders a `<time>` tag.
+
+```tsx
+<DateTime date="2025-03-15T10:30:00Z" format="full" />
+<DateTime date={new Date()} format="day" />
+```
+
+Formats: `full`, `fullWithSeconds`, `day`, `time`, `weekday`.
+
+For date ranges, use en dash with spaces: "8:00 am -- 2:00 pm".
+
+## UsageCard
+
+Usage statistics display.
+
+```tsx
+<UsageCard variant="usage">
+  <UsageCard.Header>API calls</UsageCard.Header>
+  <UsageCount count={1250} limit={5000} />
+  <UsageCard.Description>
+    <TextLink href="/billing">Upgrade plan</TextLink>
+  </UsageCard.Description>
+</UsageCard>
+```
+
+Variants: `usage` (white bg, visible border), `info` (gray bg, no border).
diff --git a/skills/guidelines/components/data-display.md b/skills/guidelines/components/data-display.md
new file mode 100644
index 0000000000..10d2c4fa41
--- /dev/null
+++ b/skills/guidelines/components/data-display.md
@@ -0,0 +1,145 @@
+# Data Display
+
+## Table
+
+```tsx
+<Table>
+  <Table.Head>
+    <Table.Row>
+      <Table.Cell>Name</Table.Cell>
+      <Table.Cell>Status</Table.Cell>
+      <Table.Cell width="60px" />
+    </Table.Row>
+  </Table.Head>
+  <Table.Body>
+    <Table.Row>
+      <Table.Cell>Blog Post</Table.Cell>
+      <Table.Cell><EntityStatusBadge entityStatus="published" /></Table.Cell>
+      <Table.Cell>
+        <Menu>
+          <Menu.Trigger>
+            <IconButton icon={<MoreHorizontalIcon />} aria-label="Actions" variant="transparent" size="small" />
+          </Menu.Trigger>
+          <Menu.List>
+            <Menu.Item>Edit</Menu.Item>
+            <Menu.Item>Delete</Menu.Item>
+          </Menu.List>
+        </Menu>
+      </Table.Cell>
+    </Table.Row>
+  </Table.Body>
+</Table>
+```
+
+| Prop | Component | Notes |
+|---|---|---|
+| `isSticky` | `Table.Head` | Sticky header |
+| `isSelected` | `Table.Row` | Highlight selected rows |
+| `isSortable` / `sortDirection` | `Table.Cell` | Sortable column header |
+| `isTruncated` | `Table.Cell` | Truncate long text |
+| `width` | `Table.Cell` | Fixed column width |
+
+**Loading state:** `Skeleton.Row` inside `Table.Body` with `rowCount` and `columnCount`.
+
+## Card
+
+```tsx
+<Card onClick={handleClick} padding="default">
+  <Heading>API Keys</Heading>
+  <Paragraph>Manage your API keys</Paragraph>
+</Card>
+```
+
+| Prop | Notes |
+|---|---|
+| `onClick` | Makes card interactive |
+| `isSelected` | Selection state |
+| `padding` | `'none'` `'default'` `'large'` |
+| `withDragHandle` | Show drag handle |
+| `ariaLabel` | Required when interactive but no visible title |
+
+## EntityList
+
+Lists of Contentful entries or assets.
+
+```tsx
+<EntityList>
+  <EntityList.Item
+    title="Homepage Banner"
+    contentType="Asset"
+    status="published"
+    withThumbnail
+    actions={<Menu>...</Menu>}
+  />
+</EntityList>
+```
+
+Status values: `published`, `draft`, `changed`, `archived`.
+
+## Accordion
+
+Secondary content not needed by default.
+
+```tsx
+<Accordion>
+  <Accordion.Item title="Advanced settings">
+    <Stack flexDirection="column" spacing="spacingM">
+      <FormControl>...</FormControl>
+    </Stack>
+  </Accordion.Item>
+</Accordion>
+```
+
+## Skeleton
+
+Show during data fetch. Never show empty state until fetch completes.
+
+```tsx
+<!-- Full area skeleton -->
+<Skeleton.Container>
+  <Skeleton.DisplayText />
+  <Skeleton.BodyText numberOfLines={3} />
+</Skeleton.Container>
+
+<!-- Table skeleton -->
+<Table.Body>
+  <Skeleton.Row rowCount={5} columnCount={3} />
+</Table.Body>
+```
+
+## Pagination
+
+```tsx
+<Pagination
+  activePage={page}
+  onPageChange={setPage}
+  totalItems={100}
+  itemsPerPage={20}
+/>
+```
+
+## List
+
+Simple bullet or numbered list.
+
+```tsx
+<List>
+  <List.Item>First item</List.Item>
+  <List.Item>Second item</List.Item>
+</List>
+<List as="ol">...</List>
+```
+
+## ProgressStepper
+
+Multi-step progress indicator.
+
+```tsx
+<ProgressStepper ariaLabel="Setup progress" activeStep={1}>
+  <ProgressStepper.Step state="complete" labelText="Create" />
+  <ProgressStepper.Step state="active" labelText="Configure" />
+  <ProgressStepper.Step state="incomplete" labelText="Deploy" />
+</ProgressStepper>
+```
+
+States: `active`, `complete`, `incomplete`, `disabled`, `error`, `warning`.
diff --git a/skills/guidelines/components/feedback.md b/skills/guidelines/components/feedback.md
new file mode 100644
index 0000000000..a045eaba7e
--- /dev/null
+++ b/skills/guidelines/components/feedback.md
@@ -0,0 +1,96 @@
+# Feedback & Status
+
+## Notification (toast)
+
+Temporary feedback after a user action. Auto-dismisses after 6 seconds.
+
+```tsx
+Notification.success('Entry published');
+Notification.error('Failed to save. Check your connection and try again.');
+Notification.success('Saved', { id: 'save-success' }); // prevent duplicates
+Notification.error('Upload failed', { duration: 0, withClose: true }); // persistent error
+```
+
+**Rules:**
+- Active voice, present tense: "Entry published" not "The entry has been published"
+- Max 1–2 sentences
+- `duration: 0` for errors that need acknowledgment
+- Use `id` to prevent duplicate toasts
+- Do not use Notification for persistent context — use Note
+
+## Note
+
+Persistent inline context. Stays visible until dismissed or the condition changes.
+
+```tsx
+<Note variant="warning" title="Unsaved changes">
+  You have unsaved changes that will be lost if you navigate away.
+</Note>
+
+<Note variant="positive">Environment published successfully.</Note>
+```
+
+| Variant | Icon | Use |
+|---|---|---|
+| `primary` | InfoIcon | General information |
+| `neutral` | InfoIcon | Neutral context |
+| `positive` | CheckCircleIcon | Success, confirmation |
+| `warning` | WarningIcon | Caution, potential issues |
+| `negative` | WarningOctagonIcon | Errors, critical issues |
+| `premium` | DiamondIcon | Paid feature context |
+
+| Prop | Type | Notes |
+|---|---|---|
+| `variant` | see above | Default: `'primary'` |
+| `title` | string | Optional heading |
+| `withCloseButton` | boolean | Adds dismiss button |
+| `onClose` | function | Pair with `withCloseButton` |
+| `icon` | ReactNode | Override default variant icon |
+
+Place Note near the relevant content, not generically at the top of the page.
+
+## Badge
+
+Labels and status indicators. Keep to one word.
+
+```tsx
+<Badge variant="positive">Published</Badge>
+<Badge variant="warning">Draft</Badge>
+<Badge variant="featured">New</Badge>
+```
+
+| Variant | Use |
+|---|---|
+| `primary` | Default |
+| `primary-filled` | Emphasized default |
+| `positive` | Published, active |
+| `negative` | Deleted, error |
+| `warning` | Draft, pending |
+| `secondary` | Muted status |
+| `featured` | Premium, new |
+
+Sizes: `default`, `small`. Use `textTransform="none"` when text is already in correct case.
+
+**For Contentful entity status, always use `EntityStatusBadge`:**
+
+```tsx
+<EntityStatusBadge entityStatus="published" />
+<EntityStatusBadge entityStatus="draft" />
+<EntityStatusBadge entityStatus="changed" />
+<EntityStatusBadge entityStatus="archived" />
+```
+
+Do not construct a raw Badge for entity status.
+
+## Spinner
+
+Full-area loading indicator.
+
+```tsx
+<Spinner size="large" />
+```
+
+Sizes: `small` (14px), `medium` (20px, default), `large` (36px).
+Variants: `default`, `primary`, `white`.
+
+For button loading, use `Button isLoading` instead of adding a Spinner.
diff --git a/skills/guidelines/components/forms.md b/skills/guidelines/components/forms.md
new file mode 100644
index 0000000000..1e66227af6
--- /dev/null
+++ b/skills/guidelines/components/forms.md
@@ -0,0 +1,156 @@
+# Forms
+
+Every input must live inside a `FormControl`. No exceptions.
+
+## FormControl
+
+The wrapper for all form fields. Propagates state to children automatically.
+
+```tsx
+<FormControl isRequired>
+  <FormControl.Label>Name</FormControl.Label>
+  <TextInput value={name} onChange={e => setName(e.target.value)} />
+  <FormControl.HelpText>The display name for this content type</FormControl.HelpText>
+</FormControl>
+
+<FormControl isRequired isInvalid={!!error}>
+  <FormControl.Label>API ID</FormControl.Label>
+  <TextInput value={apiId} onChange={e => setApiId(e.target.value)} />
+  <FormControl.ValidationMessage>{error}</FormControl.ValidationMessage>
+</FormControl>
+```
+
+**Structure order:** Label → Input → HelpText → ValidationMessage
+
+| Prop | Type | Notes |
+|---|---|---|
+| `isRequired` | boolean | Shows asterisk on label |
+| `isInvalid` | boolean | Shows validation message, red border on input |
+| `isDisabled` | boolean | Disables the input |
+| `isReadOnly` | boolean | |
+| `as` | `'div'` `'fieldset'` | Use `fieldset` for checkbox/radio groups |
+
+**Sub-components:**
+- `FormControl.Label` — required for accessibility. Use `as="legend"` inside fieldsets
+- `FormControl.HelpText` — always-visible guidance
+- `FormControl.ValidationMessage` — error text, appears when `isInvalid`
+- `FormControl.Counter` — character count
+
+Set state props on FormControl, not on the input directly.
+
+## TextInput
+
+Short free text.
+
+```tsx
+<TextInput value={val} onChange={e => setVal(e.target.value)} placeholder="e.g. Blog Post" />
+<TextInput type="search" icon={<SearchIcon />} />
+```
+
+| Prop | Type |
+|---|---|
+| `value` / `onChange` | standard |
+| `placeholder` | string |
+| `size` | `'small'` `'medium'` |
+| `icon` | ReactNode |
+| `type` | `'text'` `'email'` `'number'` `'password'` `'search'` `'url'` |
+
+Use `TextInput.Group` to pair an input with an adjacent action button.
+
+## Textarea
+
+Long-form text. Always inside FormControl.
+
+```tsx
+<Textarea value={desc} onChange={e => setDesc(e.target.value)} rows={4} />
+```
+
+## Select
+
+For 2–8 options. Never use Select for triggering actions (use Menu).
+
+```tsx
+<Select value={type} onChange={e => setType(e.target.value)}>
+  <Select.Option value="text">Text</Select.Option>
+  <Select.Option value="number">Number</Select.Option>
+</Select>
+```
+
+## Autocomplete
+
+For lists >8 items or when search is needed. Manage filtering externally.
+
+```tsx
+<Autocomplete
+  items={filteredItems}
+  onSelectItem={item => setSelected(item)}
+  onInputValueChange={val => setFilter(val)}
+  itemToString={item => item?.name ?? ''}
+/>
+```
+
+## Multiselect
+
+Multiple selection from a list.
+
+```tsx
+<Multiselect currentSelection={selected} placeholder="Select tags">
+  {tags.map(tag => (
+    <Multiselect.Option
+      key={tag.id}
+      itemId={tag.id}
+      value={tag.id}
+      label={tag.name}
+      onSelectItem={() => toggle(tag)}
+      isChecked={selected.includes(tag)}
+    />
+  ))}
+</Multiselect>
+```
+
+## Checkbox
+
+Selection that requires a save action.
+
+```tsx
+<Checkbox isChecked={checked} onChange={() => setChecked(!checked)}>
+  Enable webhooks
+</Checkbox>
+```
+
+Use `Checkbox.Group` for multiple selections. `isIndeterminate` for partial selection.
+
+## Radio
+
+Mutually exclusive single selection.
+
+```tsx
+<Radio.Group value={type} onChange={e => setType(e.target.value)}>
+  <Radio value="short">Short text</Radio>
+  <Radio value="long">Long text</Radio>
+</Radio.Group>
+```
+
+## Switch
+
+Toggle with immediate effect (no save needed).
+
+```tsx
+<Switch isChecked={enabled} onChange={() => setEnabled(!enabled)}>Dark mode</Switch>
+```
+
+Use Switch when the action takes effect immediately. Use Checkbox when a save is required.
+
+## DatePicker
+
+Calendar date input.
+
+```tsx
+<DatePicker value={date} onChange={setDate} dateFormat="day" />
+```
+
+| Prop | Type |
+|---|---|
+| `value` / `onChange` | Date |
+| `dateFormat` | `'full'` `'day'` `'time'` |
+| `minDate` / `maxDate` | Date |
diff --git a/skills/guidelines/components/layout.md b/skills/guidelines/components/layout.md
new file mode 100644
index 0000000000..c20bdeffc4
--- /dev/null
+++ b/skills/guidelines/components/layout.md
@@ -0,0 +1,139 @@
+# Layout Components
+
+The hierarchy: `Box` (base) → `Flex` (extends Box + flexbox) → `Stack` (wraps Flex, uniform gap) → `Grid` (CSS grid). `Layout` is the page-level shell.
+
+## Box
+
+The base primitive. All layout components extend it.
+
+```tsx
+<Box padding="spacingM" marginBottom="spacingL">content</Box>
+<Box as="span" display="inline" marginRight="spacingL">text</Box>
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `as` | `React.ElementType` | Render as any HTML element |
+| `display` | CSS display value | |
+| `margin`, `marginTop/Right/Bottom/Left` | Spacing token | e.g. `"spacingM"` |
+| `padding`, `paddingTop/Right/Bottom/Left` | Spacing token | |
+
+Spacing token scale: `'none'` `'spacing2Xs'` `'spacingXs'` `'spacingS'` `'spacingM'` `'spacingL'` `'spacingXl'` `'spacing2Xl'` `'spacing3Xl'` `'spacing4Xl'`
+
+## Flex
+
+Extends Box with `display: flex` and all flexbox props.
+
+```tsx
+<Flex justifyContent="space-between" alignItems="center">
+  <Subheading marginBottom="none">Users</Subheading>
+  <Button>Add user</Button>
+</Flex>
+
+<Flex flexDirection="column" gap="spacingS">
+  <Box style={{ height: '50px' }} />
+  <Box style={{ height: '50px' }} />
+</Flex>
+```
+
+| Prop | Type | Default |
+|---|---|---|
+| `flexDirection` | `'row'` `'column'` `'row-reverse'` `'column-reverse'` | — |
+| `gap` | Spacing token or CSS string | — |
+| `justifyContent` | CSS value | — |
+| `alignItems` | CSS value | — |
+| `flexWrap` | `'wrap'` `'nowrap'` | — |
+| `fullWidth` / `fullHeight` | boolean | `false` |
+| `isInline` | boolean | `false` → `inline-flex` |
+
+## Stack
+
+Shorthand for uniform-gap stacking. Use for toolbars, form field columns, button groups.
+
+```tsx
+<!-- Horizontal toolbar -->
+<Stack spacing="spacingS">
+  <Button variant="secondary">Export</Button>
+  <Button variant="primary">Publish</Button>
+</Stack>
+
+<!-- Vertical form fields -->
+<Stack flexDirection="column" spacing="spacingM">
+  <FormControl>...</FormControl>
+  <FormControl>...</FormControl>
+</Stack>
+```
+
+| Prop | Type | Default |
+|---|---|---|
+| `flexDirection` | `'row'` `'column'` | `'row'` |
+| `spacing` | Spacing token | `'spacingM'` |
+| `alignItems` | CSS value | `'center'` |
+
+Do not use Stack for reverse layouts — use `Flex` with `row-reverse` or `column-reverse`.
+
+## Grid
+
+CSS Grid layout.
+
+```tsx
+<Grid columns="1fr 2fr" rowGap="spacingM" columnGap="spacingM">
+  <Grid.Item>sidebar</Grid.Item>
+  <Grid.Item>main content</Grid.Item>
+</Grid>
+
+<Grid columns={3} columnGap="spacingL">
+  <Grid.Item>col 1</Grid.Item>
+  <Grid.Item>col 2</Grid.Item>
+  <Grid.Item>col 3</Grid.Item>
+</Grid>
+```
+
+| Prop | Type | Default |
+|---|---|---|
+| `columns` | number or CSS string | `'auto'` |
+| `rows` | number or CSS string | `'auto'` |
+| `columnGap` | Spacing token | `'spacingM'` |
+| `rowGap` | Spacing token | `'none'` |
+
+`Grid.Item` props: `area`, `columnStart/End`, `rowStart/End`, `alignSelf`, `order`.
+
+## Layout (page-level shell)
+
+Replaces the deprecated `Workbench`. Provides the app-page frame.
+
+```tsx
+<Layout
+  variant="wide"
+  header={
+    <Layout.Header>
+      <Header title="Experiences" actions={<Button variant="primary">Create</Button>} />
+    </Layout.Header>
+  }
+  leftSidebar={
+    <Layout.Sidebar>
+      <NavList>...</NavList>
+    </Layout.Sidebar>
+  }
+>
+  <Layout.Body>
+    <Table>...</Table>
+  </Layout.Body>
+</Layout>
+```
+
+| Prop | Type | Default |
+|---|---|---|
+| `variant` | `'narrow'` `'wide'` `'fullscreen'` | `'wide'` |
+| `header` | ReactNode (wrap in `Layout.Header`) | — |
+| `leftSidebar` | ReactNode (wrap in `Layout.Sidebar`) | — |
+| `rightSidebar` | ReactNode (wrap in `Layout.Sidebar`) | — |
+| `leftSidebarVariant` | `'narrow'` (280px) `'wide'` (340px) | `'narrow'` |
+| `rightSidebarVariant` | `'narrow'` (280px) `'wide'` (340px) | `'wide'` |
+| `offsetTop` | number (px) | `60` |
+
+**Rules:**
+- Always wrap body content in `Layout.Body`
+- Never nest Layout inside Layout or inside Modal
+- Set `dividerLine={true}` on Header when a right sidebar is present
+- `offsetTop={0}` for standalone apps without the Contentful navbar
diff --git a/skills/guidelines/components/navigation.md b/skills/guidelines/components/navigation.md
new file mode 100644
index 0000000000..ddfb8e6aa1
--- /dev/null
+++ b/skills/guidelines/components/navigation.md
@@ -0,0 +1,133 @@
+# Navigation & Overlays
+
+## Tabs
+
+Navigate between sections of related content. Maximum 6 tabs.
+
+```tsx
+<Tabs defaultTab="content">
+  <Tabs.List>
+    <Tabs.Tab panelId="content">Content</Tabs.Tab>
+    <Tabs.Tab panelId="settings">Settings</Tabs.Tab>
+  </Tabs.List>
+  <Tabs.Panel id="content">...</Tabs.Panel>
+  <Tabs.Panel id="settings">...</Tabs.Panel>
+</Tabs>
+```
+
+| Prop | Notes |
+|---|---|
+| `defaultTab` | Initial active tab ID |
+| `currentTab` / `onTabChange` | Controlled mode |
+| `Tabs.List variant` | `'default'` `'horizontal-divider'` `'vertical-divider'` |
+| `Tabs.Panel forceMount` | Keep mounted (for form state, animation) |
+
+Labels must be concise and describe the panel content accurately.
+
+## Modal
+
+Blocks the interface. Use only when:
+- An action needs confirmation before proceeding
+- Information is essential to the current workflow
+
+```tsx
+<Modal isShown={isOpen} onClose={() => setIsOpen(false)}>
+  <Modal.Header title="Delete content type" onClose={() => setIsOpen(false)} />
+  <Modal.Content>
+    <Paragraph>This content type and all its fields will be permanently deleted.</Paragraph>
+  </Modal.Content>
+  <Modal.Controls>
+    <Button variant="secondary" onClick={() => setIsOpen(false)}>Never mind</Button>
+    <Button variant="negative" isLoading={deleting} onClick={handleDelete}>
+      Delete content type
+    </Button>
+  </Modal.Controls>
+</Modal>
+```
+
+| Prop | Notes |
+|---|---|
+| `size` | `'small'` `'medium'` `'large'` `'fullWidth'` `'fullscreen'` |
+| `shouldCloseOnOverlayClick` | `false` for destructive modals |
+| `shouldCloseOnEscapePress` | default `true` |
+| `initialFocusRef` | Focus a specific element on open |
+
+**Rules:**
+- Title: verb + noun ("Delete content type")
+- Confirm button: verb + noun, matching the title
+- Cancel: "Never mind"
+- Never use Modal for navigation or non-essential information
+- Confirm button shows `isLoading` while action is in flight
+
+## Menu
+
+Action list triggered by a button.
+
+```tsx
+<Menu>
+  <Menu.Trigger>
+    <IconButton icon={<MoreHorizontalIcon />} aria-label="Actions" variant="secondary" />
+  </Menu.Trigger>
+  <Menu.List>
+    <Menu.Item onClick={handleEdit}>Edit</Menu.Item>
+    <Menu.Item onClick={handleDuplicate}>Duplicate</Menu.Item>
+    <Menu.Divider />
+    <Menu.Item onClick={handleDelete}>Delete</Menu.Item>
+  </Menu.List>
+</Menu>
+```
+
+Use Menu for actions. Use Select for form value choices. Never mix them.
+
+Sub-components: `Menu.Trigger`, `Menu.List`, `Menu.Item`, `Menu.Divider`, `Menu.SectionTitle`, `Menu.SubmenuTrigger`.
+
+## Tooltip
+
+Supplementary, non-critical context on hover/focus.
+
+```tsx
+<Tooltip content="Keyboard shortcut: Ctrl+S" id="save-tooltip">
+  <Button variant="primary">Save</Button>
+</Tooltip>
+```
+
+| Prop | Notes |
+|---|---|
+| `content` | Short text — one sentence max |
+| `id` | Required for ARIA |
+| `placement` | Positioning |
+| `showDelay` | Default 375ms |
+| `usePortal` | Use with `overflow: hidden` parents |
+
+**Rules:**
+- No buttons, links, or forms inside Tooltip content
+- Content must be non-critical — if the user needs this info, put it in the UI
+- Always include a unique `id`
+
+## Popover
+
+Low-level primitive. Use only when Menu/Autocomplete/Multiselect don't fit.
+
+```tsx
+<Popover isOpen={open} onClose={() => setOpen(false)}>
+  <Popover.Trigger>
+    <Button onClick={() => setOpen(true)}>Filter</Button>
+  </Popover.Trigger>
+  <Popover.Content>...</Popover.Content>
+</Popover>
+```
+
+You must implement accessibility yourself with Popover.
+
+## NavList
+
+Vertical sidebar navigation.
+
+```tsx
+<NavList aria-label="Main navigation">
+  <NavList.Item as="a" href="/experiences" isActive>Experiences</NavList.Item>
+  <NavList.Item as="a" href="/content">Content</NavList.Item>
+</NavList>
+```
+
+Items navigate only — do not use NavList items to trigger actions.
diff --git a/skills/guidelines/components/overview.md b/skills/guidelines/components/overview.md
new file mode 100644
index 0000000000..e3781d4398
--- /dev/null
+++ b/skills/guidelines/components/overview.md
@@ -0,0 +1,60 @@
+# Components
+
+All components import from `@contentful/f36-components` unless noted otherwise.
+
+```tsx
+import { Button, Stack, FormControl, TextInput } from '@contentful/f36-components';
+```
+
+## Choosing a component
+
+**I need to arrange items on screen:**
+- Toolbar / inline group with uniform gap → `Stack`
+- Complex alignment (space-between, mixed sizes) → `Flex`
+- Two-dimensional grid → `Grid`
+- Full page shell with header/sidebar → `Layout`
+- Just padding/margin → `Box`
+
+**I need user input:**
+- Short free text → `TextInput`
+- Long free text → `Textarea`
+- Pick one from ≤8 options → `Select`
+- Pick one from >8 options → `Autocomplete`
+- Toggle a setting → `Switch` (immediate effect) or `Checkbox` (requires save)
+- Pick one from a mutually exclusive group → `Radio.Group`
+- Pick multiple from a list → `Multiselect`
+- Pick a date → `DatePicker`
+
+**I need to trigger an action:**
+- Primary page action → `Button variant="primary"` (one per section max)
+- Supporting action → `Button variant="secondary"`
+- Constructive action (create, publish) → `Button variant="positive"`
+- Destructive action → `Button variant="negative"`
+- Icon-only action → `IconButton`
+- Navigation → `TextLink` (never `Button`)
+- Action list from a trigger → `Menu`
+
+**I need to show feedback:**
+- Temporary toast after action → `Notification`
+- Persistent inline context → `Note`
+- Status label → `Badge` (or `EntityStatusBadge` for Contentful entities)
+- Loading → `Skeleton` (data fetch) or `Spinner` (full area)
+
+**I need navigation/overlays:**
+- Sidebar navigation → `NavList`
+- Content sections → `Tabs` (max 6)
+- Workflow-blocking confirmation → `Modal`
+- Supplementary hover context → `Tooltip`
+
+## Component files
+
+| File | Components covered |
+|---|---|
+| `layout.md` | Box, Flex, Stack, Grid, Layout |
+| `buttons.md` | Button, IconButton, TextLink, CopyButton |
+| `forms.md` | FormControl, TextInput, Textarea, Select, Autocomplete, Multiselect, Checkbox, Radio, Switch, DatePicker |
+| `feedback.md` | Notification, Note, Badge, EntityStatusBadge, Spinner |
+| `navigation.md` | Tabs, Modal, Menu, Tooltip, Popover, NavList |
+| `data-display.md` | Table, Card, EntityList, Accordion, Collapse, Skeleton, Pagination, List, ProgressStepper |
+| `content-media.md` | Asset, Avatar, Image, DateTime, UsageCard |
+| `utility.md` | DragHandle, Pill, Typography components (DisplayText, Heading, Subheading, SectionHeading, Paragraph, Text), Header |
diff --git a/skills/guidelines/components/utility.md b/skills/guidelines/components/utility.md
new file mode 100644
index 0000000000..85d3a52524
--- /dev/null
+++ b/skills/guidelines/components/utility.md
@@ -0,0 +1,88 @@
+# Utility Components
+
+## Typography
+
+```tsx
+import { DisplayText, Heading, Subheading, SectionHeading, Paragraph, Text } from '@contentful/f36-components';
+```
+
+| Component | Size | Use |
+|---|---|---|
+| `DisplayText` | 2xl–4xl | Hero/splash headings only |
+| `Heading` | xl | Page section titles |
+| `Subheading` | l | Sub-section titles |
+| `SectionHeading` | s, 600 weight | Nav group labels, table column headers |
+| `Paragraph` | m | Body copy |
+| `Text` | any | Inline styled text with token overrides |
+
+Use the `as` prop to decouple HTML element from visual size. Never skip heading levels (h1 → h3).
+
+## Header
+
+Every page must have one. Two variants:
+
+**Title variant** — top-level pages:
+```tsx
+<Header title="Experiences" actions={<Button variant="primary">Create</Button>} />
+```
+
+**Breadcrumb variant** — subpages:
+```tsx
+<Header
+  title="Blog Post"
+  breadcrumbs={[{ label: 'Content', href: '/content' }]}
+  withBackButton
+  actions={<Button variant="positive">Publish</Button>}
+/>
+```
+
+| Prop | Notes |
+|---|---|
+| `title` | Page title text |
+| `actions` | Right-aligned action buttons |
+| `breadcrumbs` | Parent path for subpages |
+| `withBackButton` | Show back arrow |
+| `filters` | Filter controls below title |
+| `dividerLine` | Set `true` when right sidebar is present |
+
+Rules: actions slot order is secondary buttons first, primary last.
+
+## DragHandle
+
+For custom drag implementations.
+
+```tsx
+<DragHandle label="Reorder item" />
+```
+
+Card already includes this via `withDragHandle`.
+
+## Pill
+
+Tags and labels with optional close/drag.
+
+```tsx
+<Pill label="JavaScript" onClose={() => removeTag('js')} />
+<Pill label="Draft" variant="active" />
+```
+
+Variants: `idle`, `active`, `deleted`.
+
+## Icons
+
+```tsx
+import { PlusIcon, DeleteIcon, SearchIcon, MoreHorizontalIcon } from '@contentful/f36-icons';
+
+<Button startIcon={<PlusIcon />}>Add field</Button>
+<PlusIcon size="medium" color={tokens.blue600} />
+```
+
+| Size | Pixels | Use |
+|---|---|---|
+| `tiny` | 14px | Caption text, metadata |
+| `small` | 16px (default) | Nav items, form fields, buttons |
+| `medium` | 20px | Body text, headings |
+
+**Regular** = outline (default). **Duotone** = active/toggled state.
+
+Source: Phosphor library. Never use icons from other libraries.
diff --git a/skills/guidelines/composition/base-shell.md b/skills/guidelines/composition/base-shell.md
new file mode 100644
index 0000000000..788d16293c
--- /dev/null
+++ b/skills/guidelines/composition/base-shell.md
@@ -0,0 +1,66 @@
+# Base Shell
+
+Every Contentful screen uses this exact shell. Do not invent alternative chrome.
+
+```
++---------------------------------------------------------+
+|  Top bar  (52px, gray-100 background)                   |
++----------------+----------------------------------------+
+|                |  Content area                           |
+|  Sidebar       |  +------------------------------------+|
+|  (240px)       |  |  Header (title + actions)          ||
+|                |  +------------------------------------+|
+|                |  |  Page content                      ||
+|                |  +------------------------------------+|
++----------------+----------------------------------------+
+                                                [8px agent strip]
+```
+
+## Top bar
+
+Height `52px`, background `gray100`. Horizontal padding: `24px` left, `64px` right (the 64px gap is reserved for the agent strip).
+
+**Left side:** Contentful "C" logo → Space/Environment switcher pill
+**Right side:** Search icon → Help icon → User avatar (24px)
+
+**Environment switcher:**
+- Background: `green100`
+- Border: `green400`
+- Text: `green700` — "Space > Production"
+- Right-edge indicator strip: `green300`
+- Icon: rocket
+
+## Sidebar
+
+Width `240px`, white background, `shadowDefault`, top corners rounded to `12px`.
+Padding: `pt-12px pb-8px px-4px`. Inner menu: `px-12px`, gap between sections `12px`.
+
+Always implement the sidebar faithfully — replicate all sections, items, icons, and states exactly. Never stub or simplify it.
+
+**Nav item** (32px tall): `px-12px py-6px`, `gap-8px`, `border-radius: 4px`
+- Icon (16px, duotone for active) + label (body, `gray900`) + optional caret
+- Active: `blue100` background
+- Default: transparent
+- Hover: `gray100` background
+
+**Sections** (separated by `gray200` bottom border):
+1. **Setup** — Design System, Content Model
+2. **Creation** — Experiences, Content
+3. **Optimization** — Optimizations, Analytics
+4. **Platform Configuration** — Collections, AI & Automations, Taxonomy, Apps
+5. *(no title)* — Settings
+
+Section title: `12px` size, `600` weight, `gray700`, `28px` tall, `pl-12px`.
+Collapse button: transparent `IconButton` with `CaretLeft` icon, bottom-right of sidebar.
+
+## Content area
+
+Fills remaining width. White background, `shadowDefault`, top corners rounded to `12px`.
+Padding: `pt-12px px-24px`.
+
+**Top:** `Header` component — always present, never omit.
+- Use `Title` variant for top-level pages
+- Use `Breadcrumb` variant for subpages
+- Set `dividerLine={true}` when content area has a right sidebar
+
+**Below header:** unrestricted content area.
diff --git a/skills/guidelines/composition/overview.md b/skills/guidelines/composition/overview.md
new file mode 100644
index 0000000000..ba8c65e7b9
--- /dev/null
+++ b/skills/guidelines/composition/overview.md
@@ -0,0 +1,14 @@
+# Composition — Layouts & Screen Patterns
+
+This section covers how to assemble components into complete screens. Every Contentful screen follows a consistent shell and uses named patterns for common page types.
+
+## Files
+
+| File | What it covers |
+|---|---|
+| `base-shell.md` | The standard app chrome — top bar, sidebar, content area |
+| `screen-patterns.md` | Named patterns: list, detail, settings, empty state, error, confirmation, wizard, dashboard, form |
+
+## Rule
+
+Always start from the base shell and a named screen pattern. Do not invent custom chrome or layout structures. If the design does not fit a named pattern, flag it — do not improvise.
diff --git a/skills/guidelines/composition/screen-patterns.md b/skills/guidelines/composition/screen-patterns.md
new file mode 100644
index 0000000000..09303e122f
--- /dev/null
+++ b/skills/guidelines/composition/screen-patterns.md
@@ -0,0 +1,210 @@
+# Screen Patterns
+
+Named, reusable patterns for common Contentful screens. When a design calls for one of these, use it as the structural template.
+
+---
+
+## List / Index Page
+
+A collection of items with filtering and primary action. The most common pattern.
+
+```
+Header
+  title: "Experiences"
+  actions: [secondary button, primary button]
+  filters: [search input, optional filter selects]
+
+Content
+  |- Bulk action bar (when items selected)
+  |- Table or EntityList
+  |    rows: [thumbnail?, title, metadata, status badge, actions menu]
+  |- Pagination
+```
+
+**Rules:**
+- Primary action ("Create experience") is top-right in Header
+- Row actions via Menu with IconButton trigger (MoreHorizontalIcon) — not inline buttons
+- Status column uses `EntityStatusBadge`
+- Bulk selection: checkbox column left, bulk action bar above table
+- Loading: `Skeleton.Row` inside table body
+
+**Empty state (no items):** "No [items] yet" + one sentence about purpose + primary create button
+**Empty state (no search results):** `No results for "[query]"` + "Try a different search term or clear filters." + TextLink "Clear filters"
+
+---
+
+## Detail / Edit Page
+
+A single entity being viewed or edited.
+
+```
+Header
+  title: entry name (or "Untitled")
+  breadcrumbs: [parent section]
+  actions: [secondary menu, "Save" or "Publish" primary]
+
+Content (two-column when sidebar present)
+  |- Main content (fields, editor, canvas)
+  |- Right sidebar: status, metadata, publish controls
+```
+
+**Rules:**
+- `dividerLine={true}` on Header when right sidebar present
+- Publish button: `positive` variant — "Publish"
+- Save draft: `secondary` — "Save"
+- Unsaved changes: `Note variant="warning"` below Header
+- Discard: confirmation Modal before navigating away
+
+---
+
+## Settings Page
+
+```
+Header
+  title: "[Feature] settings"
+  actions: [optional "Save changes" primary]
+
+Content
+  |- Optional Tabs (if distinct categories)
+  |- Sections with Heading separator
+  |    |- FormControl fields
+  |    |- Optional Note for context
+  |- Danger zone (bottom, with negative Note)
+       |- Destructive actions
+```
+
+**Rules:**
+- Group under `Heading` / `SectionHeading` with `gray200` divider
+- Danger zone always at very bottom, visually separated
+- Destructive actions: `negative` Button → confirmation Modal
+- Inline save: `Notification.success` — don't navigate away
+
+---
+
+## Empty State
+
+When a section has no content yet.
+
+```
+Centered container (vertical + horizontal)
+  |- Icon: 48px, gray400, relevant to section (optional)
+  |- Heading: "No [items] yet"
+  |- Body: one sentence
+  |- Action: Button primary or TextLink
+```
+
+**Heading formulas:**
+- First-time: "No [content types] yet"
+- No results: `No results for "[query]"`
+- Permission: "You don't have access to [section]"
+
+**Body formulas:**
+- First-time: "[Section] lets you [purpose]. Start by [action]."
+- No results: "Try a different search term or adjust filters."
+- Error: "Something went wrong while loading [items]."
+
+Never show empty state while data is loading — show Skeleton.
+
+---
+
+## Error State
+
+```
+Centered container
+  |- Icon: WarningIcon or CloseCircleIcon, 48px, red600
+  |- Heading: "Couldn't load [section]"
+  |- Body: brief explanation + what user can do
+  |- Actions: "Try again" (primary) + optional "Go back" (secondary)
+```
+
+**Rules:**
+- "Couldn't load" not "Error 500" — humanize
+- Always offer a recovery action
+- Log technical details to console
+- Partial failures: `Note variant="negative"` inline, not full-page error
+
+---
+
+## Confirmation Dialog (Destructive)
+
+```
+Modal size="small"
+  Header: "[Delete/Remove/Archive] [item type]"
+  Content: "This will permanently [consequence]. This cannot be undone."
+  Controls:
+    Button negative: "[Delete/Remove/Archive] [item type]"
+    Button secondary: "Never mind"
+```
+
+**Rules:**
+- Title and confirm button always match: same verb + noun
+- Confirm: `negative` variant
+- Cancel: "Never mind" — never "Cancel", "No", "Go back"
+- `shouldCloseOnOverlayClick={false}`
+- Confirm shows `isLoading` while in flight
+
+---
+
+## Multi-Step Flow / Wizard
+
+```
+Layout variant="narrow" or Modal size="large"/"fullscreen"
+  |- Step indicator: "Step 2 of 4"
+  |- Header: step title
+  |- Content: step-specific form
+  |- Footer:
+       Left: "Back" (secondary, hidden on step 1)
+       Right: "Continue" (primary) or "Finish" (positive, last step)
+```
+
+**Rules:**
+- "Back" on left, "Continue" on right
+- Final step: `positive` variant — "Create [thing]" or "Finish setup"
+- Show progress indicator — never leave users guessing
+- Validate before "Continue" — inline ValidationMessage, not blocking alert
+- Allow exiting — show discard confirmation if data entered
+
+---
+
+## Dashboard / Overview
+
+```
+Header
+  title: "Overview" or space name
+  actions: optional CTA
+
+Content
+  |- Row of metric Cards (3-4 columns)
+  |- Recent activity list or EntityList
+  |- Quick action Cards
+```
+
+**Rules:**
+- Metric cards: equal width, `padding="default"`
+- Max 4 cards per row
+- Recent activity: 5–10 items, link to full list
+- Loading: `Skeleton.Container` per card
+- Empty state per section independently
+
+---
+
+## Form Page (Standalone)
+
+```
+Layout variant="narrow"
+  Header: form title
+  Content:
+    Stack of FormControl (spacing="spacingM")
+    Optional Note for context
+    Optional Accordion for advanced sections
+  Footer:
+    Button primary: "Save" or "Submit"
+    Optional Button secondary: "Cancel"
+```
+
+**Rules:**
+- Use `Layout variant="narrow"` — never full width
+- Group related fields under Heading
+- `isRequired` on FormControl for required fields
+- Validate inline, on blur or submit
+- On success: `Notification.success` + navigate to result
diff --git a/skills/guidelines/foundations/accessibility.md b/skills/guidelines/foundations/accessibility.md
new file mode 100644
index 0000000000..344dbac4d8
--- /dev/null
+++ b/skills/guidelines/foundations/accessibility.md
@@ -0,0 +1,42 @@
+# Accessibility
+
+Accessibility is non-negotiable. Every screen must work for all users.
+
+## Color contrast
+
+- Text on backgrounds must meet WCAG 2.1 AA minimum (4.5:1 for normal text, 3:1 for large text)
+- Never rely on color alone to convey meaning — always pair with text or icon
+- Interactive elements must have visible focus states
+
+## Keyboard navigation
+
+- All interactive elements must be reachable via Tab
+- Focus order must follow logical reading order
+- Modals must trap focus and restore it on close
+- Menus and dropdowns must support arrow key navigation
+- Escape must close overlays (modals, menus, tooltips)
+
+## ARIA labels
+
+- Icon-only buttons: always provide `aria-label` describing the action
+- Form inputs: always use `FormControl.Label` (renders as `<label>`)
+- Grouped inputs: use `FormControl as="fieldset"` with `Label as="legend"`
+- NavList: always provide `aria-label` on the nav element
+- ProgressStepper: `ariaLabel` is required
+
+## Screen readers
+
+- Use plain language — aim for 8th-grade reading level
+- Avoid directional instructions ("click the button on the left")
+- Use semantic HTML elements (`<nav>`, `<main>`, `<header>`, `<aside>`)
+- Do not use `aria-hidden` on content that conveys meaning
+- Skeleton loading states should include an accessible label
+
+## Focus rings
+
+Use the glow tokens for focus indicators:
+- `glowPrimary` — default focus
+- `glowNegative` — error context
+- `glowPositive` — success context
+
+These are applied automatically by Forma 36 components. Do not override or remove them.
diff --git a/skills/guidelines/foundations/icons.md b/skills/guidelines/foundations/icons.md
new file mode 100644
index 0000000000..c24559c208
--- /dev/null
+++ b/skills/guidelines/foundations/icons.md
@@ -0,0 +1,47 @@
+# Icons
+
+Forma 36 uses the **Phosphor** icon library exclusively.
+
+```tsx
+import { PlusIcon, SearchIcon, DeleteIcon } from '@contentful/f36-icons';
+```
+
+## Styles
+
+- **Regular** (outline, 2px stroke) — default state
+- **Duotone** (filled, two-tone) — active/toggled state
+
+Never use filled solid single-color icons. Never use icons from Material Icons, Heroicons, Feather, Lucide, or any other library.
+
+## Sizing
+
+Match icon size to the text it accompanies:
+
+| Context | Size | Pixels |
+|---|---|---|
+| Caption text, metadata | `tiny` | 14px |
+| Nav items, form fields, buttons | `small` (default) | 16px |
+| Body text, headings | `medium` | 20px |
+
+## Color
+
+Match icon color to its semantic role:
+
+| Role | Token |
+|---|---|
+| Default / neutral | `gray900` |
+| Muted / decorative | `gray600` |
+| Active / primary action | `blue600` |
+| On dark backgrounds | `colorWhite` |
+| Success | `green600` |
+| Destructive / error | `red600` |
+| Warning | `orange400` |
+| Premium / new feature | `purple600` (sparingly) |
+
+## Labels
+
+Most icons need a visible text label. Icons may appear without labels only when:
+- Universally understood (magnifying glass for search, question mark for help, gear for settings)
+- In a consistent, expected position
+
+When in doubt, add a label or tooltip. Icon-only buttons always need `aria-label`.
diff --git a/skills/guidelines/foundations/overview.md b/skills/guidelines/foundations/overview.md
new file mode 100644
index 0000000000..d0ee04364a
--- /dev/null
+++ b/skills/guidelines/foundations/overview.md
@@ -0,0 +1,9 @@
+# Foundations
+
+Design foundations that apply across every screen and component.
+
+| File | What it covers |
+|---|---|
+| `writing.md` | Voice, tone, sentence case rules, error messages, button labels, confirmation dialogs |
+| `icons.md` | Phosphor library, sizing, color rules, when labels are optional |
+| `accessibility.md` | Contrast, keyboard navigation, ARIA labels, screen reader guidance |
diff --git a/skills/guidelines/foundations/writing.md b/skills/guidelines/foundations/writing.md
new file mode 100644
index 0000000000..6c83e79843
--- /dev/null
+++ b/skills/guidelines/foundations/writing.md
@@ -0,0 +1,86 @@
+# Writing
+
+The Contentful interface is clear, direct, respectful, and calm.
+
+## Voice
+
+| Quality | What it means |
+|---|---|
+| **Clear** | Say exactly what you mean. No jargon, no hedging. |
+| **Direct** | Lead with the action or outcome. Do not bury the point. |
+| **Respectful** | Treat users as capable adults. Do not over-explain. |
+| **Calm** | Even error messages stay composed. The interface never panics. |
+
+The voice is never casual, never corporate, never clever, never apologetic.
+
+## Sentence case
+
+All text in the interface uses sentence case. No exceptions.
+
+- "Content types" not "Content Types"
+- "Add field" not "Add Field"
+- "Published" not "PUBLISHED"
+
+## Button and link labels
+
+Always start with a verb. Max 3 words.
+
+- "Add field" — not "New field"
+- "Delete entry" — not "Entry deletion"
+- "Publish changes" — not "Changes"
+
+## Error messages
+
+Tell the user exactly what went wrong and what to do next.
+
+- "This field is required. Add a value before publishing."
+- "The entry couldn't be saved. Check your connection and try again."
+
+Do not write: "Something went wrong", "Error", "Invalid input".
+
+## Forbidden phrases
+
+Do not use these phrases anywhere in the interface:
+
+| Phrase | Instead |
+|---|---|
+| "Click here" | Describe the action |
+| "Please" | Direct language is respectful |
+| "Sorry" | Fix the problem |
+| "Successfully" | Just state the result: "Entry published" |
+| "Are you sure?" | State what will happen: "This will permanently delete the entry" |
+| "Learn more" | Link to the specific topic |
+
+## Confirmation dialogs
+
+For destructive actions:
+
+- **Title:** verb + noun ("Delete content type")
+- **Body:** one sentence stating the consequence ("This content type and all its fields will be permanently deleted.")
+- **Confirm:** verb + noun matching the title ("Delete content type")
+- **Cancel:** "Never mind"
+
+Never use "Cancel", "Go back", or "No" as the cancel label.
+
+## Notifications
+
+- Active voice, present tense: "Entry published"
+- Max 1–2 sentences
+- Auto-dismiss after 6 seconds unless error
+
+## Tooltips
+
+- One sentence maximum
+- Non-critical information only
+- No links or interactive elements
+
+## Status labels
+
+| Status | Label |
+|---|---|
+| Published and current | "Published" |
+| Published with changes | "Changed" |
+| Never published | "Draft" |
+| Removed from publication | "Archived" |
+
+Do not invent custom status labels for standard Contentful entity states.
diff --git a/skills/guidelines/overview.md b/skills/guidelines/overview.md
new file mode 100644
index 0000000000..3f1807969b
--- /dev/null
+++ b/skills/guidelines/overview.md
@@ -0,0 +1,36 @@
+# Forma 36 — Contentful Design System
+
+Forma 36 is the design language of Contentful. Every screen, component, and interaction must feel like it belongs in the Contentful product — calm, trustworthy, and focused on the user's task.
+
+## Product character
+
+Contentful is a professional content platform used daily by developers, editors, and designers. The UI is never decorative, never surprising, never clever. It is clear, consistent, and accessible.
+
+**Density:** Medium — generous whitespace, but no wasted space. Every element earns its place.
+**Surfaces:** White panels with subtle shadows on a light gray (`#F7F9FA`) background. No gradients, no colored surfaces except for semantic meaning.
+**Color philosophy:** Color carries meaning. Blue = primary action. Green = success/published. Red = danger/error. Orange = warning/draft. Purple = premium (sparingly). Never use color as decoration.
+
+## Reading order
+
+When building a Forma 36 interface, read these guidelines in this order:
+
+1. **`setup.md`** — Install dependencies and configure your project
+2. **`tokens/`** — Learn the spacing, color, typography, shadow, and border tokens
+3. **`components/`** — Look up the specific components you need
+4. **`composition/`** — Follow the layout shell and screen pattern templates
+5. **`foundations/`** — Follow writing, icon, and accessibility rules
+
+## Critical rules
+
+These rules apply everywhere. Do not override them:
+
+- Never use raw hex colors — always use tokens from `@contentful/f36-tokens`
+- Never use arbitrary spacing — every gap is a spacing token
+- Never skip the `Header` component on any page
+- Never use more than one primary button per screen section
+- Never use Title Case — sentence case only
+- Never use `Workbench` — it is deprecated, use `Layout`
+- Never use icons from libraries other than Phosphor
+- Cancel button for destructive actions is always "Never mind"
+- Every input must live inside a `FormControl`
+- Color must never be the only way to convey meaning
diff --git a/skills/guidelines/setup.md b/skills/guidelines/setup.md
new file mode 100644
index 0000000000..73e7d29a87
--- /dev/null
+++ b/skills/guidelines/setup.md
@@ -0,0 +1,59 @@
+# Setup
+
+## Dependencies
+
+Install the Forma 36 packages:
+
+```bash
+npm install @contentful/f36-components @contentful/f36-tokens @contentful/f36-icons
+```
+
+Forma 36 requires React 18 and is compatible with Vite.
+
+## CSS
+
+Import the Forma 36 stylesheet at the root of your application:
+
+```tsx
+import '@contentful/f36-components/dist/styles.css';
+```
+
+This import is required. Components will render without styles if you skip it.
+
+## Font
+
+Forma 36 uses the **Geist** typeface by Vercel. Load it from the Contentful CDN:
+
+```html
+<link rel="stylesheet" href="https://cdn.f36.contentful.com/fonts/geist.css" />
+```
+
+Fallback stack: `-apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif`.
+
+Apply `font-feature-settings: 'ss05' 1` on all Geist text to activate stylistic alternates.
+
+## Tokens
+
+Import tokens for use in inline styles and custom CSS:
+
+```tsx
+import tokens from '@contentful/f36-tokens';
+
+// Use in inline styles
+<div style={{ padding: tokens.spacingM, color: tokens.colorPrimary }} />
+
+// Or import individual tokens
+import { spacingM, colorPrimary } from '@contentful/f36-tokens';
+```
+
+Do not hardcode hex values, pixel measurements, or font stacks. Always use the token.
+
+## Icons
+
+All icons come from the Phosphor library, packaged in `@contentful/f36-icons`:
+
+```tsx
+import { PlusIcon, SearchIcon, DeleteIcon } from '@contentful/f36-icons';
+```
+
+Do not use Material Icons, Heroicons, Feather, Lucide, or any other icon library.
diff --git a/skills/guidelines/tokens/color.md b/skills/guidelines/tokens/color.md
new file mode 100644
index 0000000000..d3682489a6
--- /dev/null
+++ b/skills/guidelines/tokens/color.md
@@ -0,0 +1,117 @@
+# Color Tokens
+
+Color in Forma 36 carries meaning. It is never decorative.
+
+## Choosing a color
+
+Ask yourself: **what does this color communicate?**
+
+- Primary interactive action → Blue
+- Success or published state → Green
+- Danger, error, or destructive action → Red
+- Warning or draft/unpublished state → Orange
+- Premium or paid feature → Purple (use sparingly)
+- Neutral surface or text → Gray scale
+
+If the answer is "it looks nice" — do not use that color. Use gray or white instead.
+
+## Semantic tokens (use these first)
+
+These express intent, not shade. Reach for them by default.
+
+| Token | Hex | Use |
+|---|---|---|
+| `colorPrimary` | `#0059C8` | Primary interactive actions, links |
+| `colorPositive` | `#006D23` | Success, published state, constructive actions |
+| `colorNegative` | `#BD002A` | Errors, destructive actions, deleted state |
+| `colorWarning` | `#CC4500` | Warnings, draft/unpublished state |
+
+## Text color tokens
+
+| Token | Hex | Use |
+|---|---|---|
+| `colorTextDark` | `#111B2B` | Highest-contrast text — headings, primary labels |
+| `colorTextBase` | `#1B273A` | Default body text |
+| `colorTextMid` | `#414D63` | Secondary labels, section titles |
+| `colorTextLight` | `#5A657C` | Tertiary text, captions, hints |
+| `colorTextLightest` | `#67728A` | Placeholder text, inactive labels |
+
+## Gray scale
+
+| Token | Hex | Use |
+|---|---|---|
+| `gray100` | `#F7F9FA` | Page background |
+| `gray200` | `#E7EBEE` | Dividers, subtle borders |
+| `gray300` | `#CFD9E0` | Input outlines, borders |
+| `gray400` | `#AEC1CC` | Disabled borders |
+| `gray500` | `#67728A` | Muted icons, placeholder text |
+| `gray600` | `#5A657C` | Muted/secondary icons |
+| `gray700` | `#414D63` | Section heading text |
+| `gray800` | `#1B273A` | Strong secondary text |
+| `gray900` | `#111B2B` | Primary text, nav labels |
+
+## Blue (primary)
+
+| Token | Hex | Use |
+|---|---|---|
+| `blue100` | `#E8F5FF` | Active nav item background |
+| `blue200` | `#CEECFF` | Hover on primary elements |
+| `blue600` | `#0059C8` | Primary action — buttons, links, active icons |
+| `blue700` | `#0041AB` | Pressed state |
+
+## Green (positive)
+
+| Token | Hex | Use |
+|---|---|---|
+| `green100` | `#EAF9E8` | Environment switcher background |
+| `green300` | `#9ED696` | Environment indicator strip |
+| `green400` | `#5DB057` | Environment switcher border |
+| `green600` | `#006D23` | Published status, success text |
+| `green700` | `#00550C` | Environment switcher text |
+
+## Red (negative)
+
+| Token | Hex | Use |
+|---|---|---|
+| `red100` | `#FFF2F2` | Error field background |
+| `red600` | `#BD002A` | Error text, destructive buttons |
+| `red700` | `#990017` | Pressed destructive state |
+
+## Orange (warning)
+
+| Token | Hex | Use |
+|---|---|---|
+| `orange100` | `#FFF2E4` | Warning note background |
+| `orange400` | `#F07F23` | Warning icons |
+| `orange500` | `#CC4500` | Draft/unpublished state, warning text |
+
+## Purple (premium — use sparingly)
+
+| Token | Hex | Use |
+|---|---|---|
+| `purple100` | `#F7F2FF` | Premium feature background |
+| `purple500` | `#8553E7` | Premium icons |
+| `purple600` | `#6C3ECF` | Premium label, "new feature" highlight |
+
+## Yellow (last resort)
+
+| Token | Hex |
+|---|---|
+| `yellow400` | `#FFC835` |
+
+Only use yellow when no other color communicates the meaning. This is rare.
+
+## Absolute
+
+| Token | Hex |
+|---|---|
+| `colorWhite` | `#FFFFFF` |
+| `colorBlack` | `#0C141C` |
+
+## Rules
+
+- Never use color as pure decoration
+- Never rely on color alone to convey meaning — always pair with text or icon
+- Blue is reserved for primary interactive elements — do not use it decoratively
+- Active nav items use `blue100` as background, not a blue text color
+- Do not use raw hex values — always use the token name
diff --git a/skills/guidelines/tokens/effects.md b/skills/guidelines/tokens/effects.md
new file mode 100644
index 0000000000..1f1edf9061
--- /dev/null
+++ b/skills/guidelines/tokens/effects.md
@@ -0,0 +1,72 @@
+# Effects Tokens
+
+Shadows, border radius, z-index, transitions, and focus rings.
+
+## Shadows
+
+| Token | CSS value | Use |
+|---|---|---|
+| `shadowDefault` | `0px 0px 0px 1px rgba(25,37,50,.10), 0px 3px 7px -3px rgba(25,37,50,.10), 0px 6px 12px -2px rgba(25,37,50,.10)` | Panels, sidebar, content area, cards |
+| `shadowHeavy` | `0px 0px 0px 1px rgba(25,37,50,.10), 0px -6px 16px -6px rgba(25,37,50,.03), 0px 8px 16px -8px rgba(25,37,50,.20), 0px 13px 27px -5px rgba(25,37,50,.15)` | Elevated modals, popovers |
+| `shadowButton` | `0px 1px 0px rgb(25,37,50,.10)` | Secondary and transparent buttons |
+| `insetBoxShadowDefault` | `inset 0px 2px 0px rgba(225,228,232,.20)` | Pressed/active input states |
+
+Do not invent custom shadows. These four values are all that exist.
+
+## Focus rings (glow tokens)
+
+Applied on `:focus-visible` for accessible focus indicators.
+
+| Token | Use |
+|---|---|
+| `glowPrimary` | Primary input/button focus |
+| `glowNegative` | Error input focus |
+| `glowPositive` | Success input focus |
+| `glowWarning` | Warning input focus |
+| `glowMuted` | Neutral focus |
+
+All glow tokens render as `0px 0px 0px 3px` with a color-appropriate light shade.
+
+## Border radius
+
+Only two values are exported as tokens:
+
+| Token | Value | Use |
+|---|---|---|
+| `borderRadiusSmall` | 4px | Nav items, badges, small chips |
+| `borderRadiusMedium` | 6px | Buttons, inputs, menus |
+
+Design conventions (not exported tokens — use inline styles):
+
+| Value | Use |
+|---|---|
+| `12px` | Panels, cards, modals, sidebar |
+| `100px` | Avatars, pill-shaped elements |
+
+Top-only radius for panels flush to the bottom: `border-radius: 12px 12px 0 0`.
+
+Do not use rounded corners outside this set: 4px, 6px, 12px, 100px.
+
+## Z-index
+
+| Token | Value | Use |
+|---|---|---|
+| `zIndexNegative` | -1 | Behind-everything layer |
+| `zIndexWorkbench` | 0 | Page base layer |
+| `zIndexDefault` | 1 | Normal stacking |
+| `zIndexWorkbenchHeader` | 10 | Sticky headers |
+| `zIndexModal` | 100 | Modals, dialogs |
+| `zIndexModalContent` | 101 | Modal content above overlay |
+| `zIndexDropdown` | 1000 | Menus, dropdowns |
+| `zIndexTooltip` | 10000 | Tooltips |
+| `zIndexNotification` | 100000 | Toast notifications |
+
+## Transitions
+
+| Token | Value | Use |
+|---|---|---|
+| `transitionDurationShort` | 0.1s | Micro interactions (hover, focus ring) |
+| `transitionDurationDefault` | 0.2s | Standard transitions (collapse, fade) |
+| `transitionDurationLong` | 0.3s | Larger movements (sidebar, modal) |
+| `transitionEasingDefault` | ease-in-out | Default easing |
+| `transitionEasingCubicBezier` | cubic-bezier(0.13, 0.62, 0.11, 0.99) | Spring-like emphasis |
diff --git a/skills/guidelines/tokens/overview.md b/skills/guidelines/tokens/overview.md
new file mode 100644
index 0000000000..7678fa0c0a
--- /dev/null
+++ b/skills/guidelines/tokens/overview.md
@@ -0,0 +1,25 @@
+# Tokens
+
+All design tokens live in `@contentful/f36-tokens`. Never use raw values — always reference the token name.
+
+```tsx
+import tokens from '@contentful/f36-tokens';
+```
+
+## Token philosophy
+
+Tokens are the single source of truth for every visual property. They ensure consistency across components, screens, and contributors. When you use a token, the design system can evolve without breaking your code.
+
+**Rules:**
+- Do not hardcode hex colors, pixel values, font sizes, or shadow strings
+- If a value exists as a token, use the token
+- If no token exists for the value you need, the value is probably wrong — check the design
+
+## Token groups
+
+| File | What it covers |
+|---|---|
+| `color.md` | Semantic colors, gray scale, blue/green/red/orange/purple/yellow palettes |
+| `typography.md` | Font families, sizes, weights, line heights, letter spacing |
+| `spacing.md` | The spacing scale (4px–80px) and how to apply it |
+| `effects.md` | Shadows, border radius, z-index, transitions, focus rings |
diff --git a/skills/guidelines/tokens/spacing.md b/skills/guidelines/tokens/spacing.md
new file mode 100644
index 0000000000..1b7c70cc2d
--- /dev/null
+++ b/skills/guidelines/tokens/spacing.md
@@ -0,0 +1,54 @@
+# Spacing Tokens
+
+Spacing follows a fixed scale. Use these values only — never arbitrary pixel values.
+
+## The scale
+
+| Token | Value | Rem | Use |
+|---|---|---|---|
+| `spacing2Xs` | 4px | 0.25rem | Icon gaps, tight groupings |
+| `spacingXs` | 8px | 0.5rem | Between related items |
+| `spacingS` | 12px | 0.75rem | Component internal padding |
+| `spacingM` | 16px | 1rem | Standard padding |
+| `spacingL` | 24px | 1.5rem | Section padding |
+| `spacingXl` | 32px | 2rem | Large section gaps |
+| `spacing2Xl` | 48px | 3rem | Page-level separation |
+| `spacing3Xl` | 64px | 4rem | Large page gaps |
+| `spacing4Xl` | 80px | 5rem | Maximum spacing |
+
+## How to apply spacing
+
+Components carry no external margin by default. Use layout wrappers or inline tokens.
+
+**Layout component props:**
+```tsx
+<Stack spacing="spacingM" />
+<Flex gap="spacingS" />
+<Box padding="spacingM" marginBottom="spacingL" />
+```
+
+**Inline styles (when layout props are insufficient):**
+```tsx
+<div style={{ padding: tokens.spacingM, gap: tokens.spacingS }} />
+```
+
+## Choosing the right spacing
+
+- Between items in a group (buttons, badges) → `spacingXs` (8px)
+- Internal padding of a component → `spacingS` (12px) or `spacingM` (16px)
+- Between sections on a page → `spacingL` (24px) or `spacingXl` (32px)
+- Page-level top/bottom margins → `spacing2Xl` (48px)
+
+## Content width tokens
+
+| Token | Value | Use |
+|---|---|---|
+| `contentWidthDefault` | 1280px | Standard page max-width (`Layout variant="wide"`) |
+| `contentWidthText` | 768px | Narrow content (`Layout variant="narrow"`, forms) |
+| `contentWidthFull` | 100% | Fullscreen (`Layout variant="fullscreen"`) |
+
+## Rules
+
+- Never use a spacing value outside this scale
+- Never set margin or padding to an arbitrary pixel value
+- If the spacing you need does not exist in the scale, the design is probably wrong
diff --git a/skills/guidelines/tokens/typography.md b/skills/guidelines/tokens/typography.md
new file mode 100644
index 0000000000..abf9b88457
--- /dev/null
+++ b/skills/guidelines/tokens/typography.md
@@ -0,0 +1,79 @@
+# Typography Tokens
+
+The typeface is **Geist** by Vercel. Always use composite type classes — do not set `font-size` independently from `font-weight` and `line-height`.
+
+## Font families
+
+| Token | Stack |
+|---|---|
+| `fontStackPrimary` | `Geist Sans, -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial, sans-serif` |
+| `fontStackMonospace` | `Geist Mono, SFMono-Regular, Consolas, Liberation Mono, Menlo, monospace` |
+
+Always use `fontStackPrimary`. Never hardcode `"Geist"` without the fallback stack. Load the font from `https://cdn.f36.contentful.com`.
+
+## Font sizes
+
+| Token | Value | Use |
+|---|---|---|
+| `fontSize4Xl` | 3rem | Hero display text |
+| `fontSize3Xl` | 2.25rem | Large display |
+| `fontSize2Xl` | 1.5rem | Page-level headings |
+| `fontSizeXl` | 1.25rem | Section headings |
+| `fontSizeL` | 1rem | Large body |
+| `fontSizeM` | 0.875rem | **Default body** — most interface text |
+| `fontSizeS` | 0.75rem | Captions, metadata, section labels |
+
+## Font weights
+
+| Token | Value | Use |
+|---|---|---|
+| `fontWeightNormal` | 400 | All body text |
+| `fontWeightMedium` | 500 | Emphasized labels, active states |
+| `fontWeightDemiBold` | 600 | Headings, section titles, nav group labels |
+
+Do not use `700` (bold) or `300` (light). Forma 36 uses only these three weights.
+
+## Line heights
+
+| Token | Value | Use |
+|---|---|---|
+| `lineHeightDefault` | 1.5 | Body text |
+| `lineHeightCondensed` | 1.25 | Nav items, badges, compact UI |
+
+## Letter spacing
+
+| Token | Value |
+|---|---|
+| `letterSpacingDefault` | 0rem |
+| `letterSpacingWide` | 0.1rem |
+
+Forma 36 uses `0` letter spacing by default. Do not add tracking to Geist.
+
+## Composite type roles
+
+When implementing text, combine tokens like this:
+
+| Role | Size | Weight | Line height | Use |
+|---|---|---|---|---|
+| Display | `fontSize2Xl`+ | `fontWeightDemiBold` | `lineHeightDefault` | Page titles, hero text |
+| Section heading | `fontSizeS` | `fontWeightDemiBold` | `lineHeightCondensed` | Nav group labels, table headers |
+| Body (default) | `fontSizeM` | `fontWeightNormal` | `lineHeightDefault` | All interface copy |
+| Body medium | `fontSizeM` | `fontWeightMedium` | `lineHeightDefault` | Emphasized labels |
+| Small / caption | `fontSizeS` | `fontWeightNormal` | `lineHeightDefault` | Metadata, hints |
+
+## High-density variants
+
+For compact UI contexts (dense tables, toolbar items):
+
+| Token | Value | Use |
+|---|---|---|
+| `fontSizeMHigh` | 0.75rem | Dense body (= default `fontSizeS`) |
+| `fontSizeSHigh` | 0.625rem | Dense caption |
+
+## Rules
+
+- Apply `font-feature-settings: 'ss05' 1` on all Geist text
+- Line height: `1.5` default, `1.25` condensed (nav items, badges)
+- Letter spacing: `0` for all sizes
+- Never mix more than two weights on a single screen
+- Labels are sentence case — never Title Case or ALL CAPS
diff --git a/skills/screen-patterns.md b/skills/screen-patterns.md
deleted file mode 100644
index 7d3c57e189..0000000000
--- a/skills/screen-patterns.md
+++ /dev/null
@@ -1,255 +0,0 @@
-# Forma 36 — Screen Patterns
-
-Named, reusable patterns for the most common Contentful UI screens. When a design calls for one of these, use this as the structural template — not a blank canvas.
-
----
-
-## 1. List / Index Page
-
-The most common pattern in Contentful. A collection of items (entries, content types, assets, apps) with filtering and primary action.
-
-```
-Header
-  title: "Experiences"
-  actions: [secondary button, primary button]
-  filters: [search input, optional filter selects]
-
-Content area
-  ├── Bulk action bar (appears when items are selected)
-  ├── Table or EntityList
-  │     rows: [thumbnail?, title, metadata columns, status badge, actions menu]
-  └── Pagination
-```
-
-**Rules:**
-- Primary action ("Create experience") is always top-right in the Header
-- Empty state shows when no items exist OR when search returns no results (different messages for each)
-- Row actions via `Menu` with `IconButton` trigger (MoreHorizontal icon) — not inline buttons
-- Status column uses `EntityStatusBadge`
-- Bulk selection: checkbox column left, bulk action bar appears above table
-- Loading state: show `Skeleton.Row` inside the table body
-
-**Empty state (no items):**
-- Heading: "No [items] yet"
-- Body: one sentence describing the purpose of this section
-- Action: primary button to create the first item
-
-**Empty state (filtered, no results):**
-- Heading: "No results for "[query]""
-- Body: "Try a different search term or clear filters."
-- Action: TextLink "Clear filters"
-
----
-
-## 2. Detail / Edit Page
-
-A single entity being viewed or edited. Common for entries, content types, experience editors.
-
-```
-Header
-  title: entry name (or "Untitled" if new)
-  breadcrumbs: [parent section]
-  actions: [secondary actions menu, "Save" or "Publish" primary]
-
-Content area (two-column when sidebar present)
-  ├── Main content area (fields, editor, canvas)
-  └── Right sidebar: status, metadata, publish controls, linked entries
-```
-
-**Rules:**
-- `dividerLine={true}` on Header when right sidebar is present
-- Status in sidebar uses `EntityStatusBadge`
-- Publish button is `positive` variant — "Publish"
-- Save draft is `secondary` — "Save"
-- Unsaved changes: show a `Note variant="warning"` below the Header, not a blocking modal
-- Discard changes: show a confirmation Modal before navigating away
-
----
-
-## 3. Settings Page
-
-Configuration of a feature, app, or space setting.
-
-```
-Header
-  title: "[Feature] settings"
-  actions: [optional "Save changes" primary button]
-
-Content area
-  ├── Optional: Tabs (if settings have distinct categories)
-  ├── Sections with Heading separator
-  │     ├── FormControl fields
-  │     └── Optional Note for context
-  └── Danger zone section (at bottom, with negative Note)
-        └── Destructive actions (delete, reset, disable)
-```
-
-**Rules:**
-- Group related settings under a `Heading` or `SectionHeading` with a `gray/200` divider
-- Danger zone (destructive actions) always goes at the very bottom, separated visually
-- Destructive actions in danger zone: `negative` variant `Button`, always trigger a confirmation Modal
-- Inline save: show `Notification.success` after saving — don't navigate away
-- Auto-save: show a subtle "Saving…" Spinner + "Saved" text near the field or in a status area
-
----
-
-## 4. Empty State
-
-Used when a section has no content yet — first-time experience, no search results, or after clearing filters.
-
-```
-Centered container (vertical + horizontal center of content area)
-  ├── Icon (optional): 48px, gray/400, relevant to the section
-  ├── Heading: "No [items] yet"
-  ├── Body: one sentence describing purpose or next step
-  └── Primary action: Button variant="primary" or TextLink
-```
-
-**Heading formulas:**
-- First-time: "No [content types] yet"
-- No search results: `No results for "[query]"`
-- Permission-restricted: "You don't have access to [section]"
-
-**Body formulas:**
-- First-time: "[Section] lets you [what it does]. Start by [first action]."
-- No results: "Try a different search term or [adjust filters]."
-- Error: "Something went wrong while loading [items]. [Retry link]."
-
-**Rules:**
-- Never show an empty state while data is still loading — show Skeleton instead
-- Never show a generic "No data" — always be specific about what's missing and what to do
-- Keep body copy to one sentence
-- Only one action in an empty state — the most obvious next step
-
----
-
-## 5. Error State
-
-When a page or section fails to load or an operation fails unrecoverably.
-
-```
-Centered container
-  ├── Icon: WarningIcon or CloseCircleIcon, 48px, red/600
-  ├── Heading: "Couldn't load [section]"
-  ├── Body: brief explanation + what the user can do
-  └── Actions: "Try again" (primary) + optional "Go back" (secondary)
-```
-
-**Rules:**
-- "Couldn't load" not "Error 500" or technical codes — humanize
-- Always offer a clear recovery action ("Try again", "Go back", "Contact support")
-- Log technical details to console; show human language in the UI
-- For partial failures (one section fails, rest loads): use `Note variant="negative"` inline, not a full-page error
-
----
-
-## 6. Confirmation Dialog (Destructive Action)
-
-Triggered before any irreversible action.
-
-```
-Modal size="small"
-  Header: "[Delete/Remove/Archive] [item type]"
-  Content:
-    Paragraph: "This will permanently [consequence]. This cannot be undone."
-    Optional: list of what will be affected
-  Controls:
-    Button variant="negative": "[Delete/Remove/Archive] [item type]"
-    Button variant="secondary": "Never mind"
-```
-
-**Rules:**
-- Title and confirm button always match: same verb + noun
-- Confirm button is `negative` variant — always
-- Cancel is always "Never mind" — never "Cancel", "No", or "Go back"
-- Body: state the consequence specifically — never vague ("This action cannot be undone")
-- `shouldCloseOnOverlayClick={false}` for destructive modals — user must make an explicit choice
-- Confirm button shows `isLoading` while the action is in flight
-
----
-
-## 7. Multi-Step Flow / Wizard
-
-Onboarding, content type creation, or any guided multi-step process.
-
-```
-Layout variant="narrow" or Modal size="large" / "fullscreen"
-  ├── Step indicator (top, horizontal) — "Step 2 of 4"
-  ├── Header: step title
-  ├── Content: step-specific form or information
-  └── Footer controls:
-        ├── Left: "Back" (secondary, or hidden on step 1)
-        └── Right: "Continue" (primary) or "Finish" (positive, last step)
-```
-
-**Rules:**
-- "Back" on left, "Continue" on right — never reversed
-- Final step confirm button: `positive` variant — "Create [thing]" or "Finish setup"
-- Show a progress indicator (step count or progress bar) — never leave users wondering how long the flow is
-- Validate before allowing "Continue" — show `ValidationMessage` inline, not a blocking alert
-- Allow exiting the flow — show discard confirmation if data has been entered
-
----
-
-## 8. Dashboard / Overview Page
-
-High-level summary of a space or feature — metrics, recent activity, quick actions.
-
-```
-Header
-  title: "Overview" or space/project name
-  actions: optional primary CTA
-
-Content area
-  ├── Row of metric Cards (3–4 columns)
-  ├── Recent activity list or EntityList
-  └── Quick action Cards or links
-```
-
-**Rules:**
-- Cards in metric rows: equal width, consistent padding `default`
-- No more than 4 metric cards in a row before wrapping or reorganizing into a different layout
-- "Recent activity" shows last 5–10 items — link to full list
-- Loading: show `Skeleton.Container` per card, not a full-page spinner
-- Empty state per section independently — not one global empty state for the whole dashboard
-
----
-
-## 9. Form Page (Standalone)
-
-A dedicated page for a single form — app configuration, user preferences, invite flow.
-
-```
-Layout variant="narrow"
-  Header: form title
-  Content:
-    Stack of FormControl fields (spacing="spacingM")
-    Optional: Note for context or instructions
-    Optional: Accordion for advanced/optional sections
-  Footer or inline:
-    Button variant="primary": "Save" or "Submit"
-    Optional Button variant="secondary": "Cancel" (navigates back)
-```
-
-**Rules:**
-- Use `Layout variant="narrow"` to keep forms readable — never stretch a form to full width
-- Group related fields under a `Heading` — don't list 15 fields in one undifferentiated block
-- Required fields: mark with `isRequired` on `FormControl` — the asterisk appears automatically
-- Validation: inline, on blur or on submit — never a separate error summary page
-- On success: `Notification.success` + navigate to the result, or stay on form with a success state
-
----
-
-## Navigation Hierarchy
-
-When building multi-level navigation:
-
-| Level | Pattern |
-|---|---|
-| Top-level sections | Left sidebar `M1NavigationSidebarMain` sections |
-| Sub-sections within a section | Tabs in the content area |
-| Drill-down to a single item | Header with Breadcrumb + back button |
-| Related views on a single item | Tabs in the detail page content area |
-
-**Never use modals as navigation.** A modal should complete a task, not replace a page.
-**Never use Tabs at the sidebar level** — sidebar items navigate between sections, not tabs.
diff --git a/skills/tokens.md b/skills/tokens.md
deleted file mode 100644
index 3d856b03d9..0000000000
--- a/skills/tokens.md
+++ /dev/null
@@ -1,218 +0,0 @@
-# Forma 36 — Design Tokens
-
-All values come from `@contentful/f36-tokens`. Never use raw hex values or arbitrary numbers in code — always use the token name. This ensures the UI stays in sync with the design system.
-
-```js
-import tokens from '@contentful/f36-tokens';
-// or individual tokens:
-import { colorPrimary, spacingM } from '@contentful/f36-tokens';
-```
-
----
-
-## Color Tokens
-
-### Semantic (use these first)
-
-These are the tokens to reach for by default. They express intent, not shade.
-
-| Token | Value | Meaning |
-|---|---|---|
-| `colorPrimary` | `#0059C8` | Primary interactive actions, links |
-| `colorPositive` | `#006D23` | Success, published state, constructive |
-| `colorNegative` | `#BD002A` | Errors, destructive actions, deleted |
-| `colorWarning` | `#CC4500` | Warnings, draft/unpublished state |
-| `colorTextDark` | `#111B2B` | Primary text — highest contrast |
-| `colorTextBase` | `#1B273A` | Default body text |
-| `colorTextMid` | `#414D63` | Secondary labels, section titles |
-| `colorTextLight` | `#5A657C` | Tertiary text, captions |
-| `colorTextLightest` | `#67728A` | Placeholder text, inactive |
-
-### Gray Scale
-
-Used for surfaces, borders, and text.
-
-| Token | Hex | Common use |
-|---|---|---|
-| `gray100` | `#F7F9FA` | Page background |
-| `gray200` | `#E7EBEE` | Dividers, subtle borders |
-| `gray300` | `#CFD9E0` | Borders, input outlines |
-| `gray400` | `#B4C3CC` | Disabled borders |
-| `gray500` | `#8D9BA6` | Muted icons |
-| `gray600` | `#536171` | Muted/secondary icons |
-| `gray700` | `#414D63` | Section heading text |
-| `gray800` | `#2A3546` | Strong secondary text |
-| `gray900` | `#111B2B` | Primary text, nav labels |
-
-### Blue (Primary)
-
-| Token | Hex | Common use |
-|---|---|---|
-| `blue100` | `#E8F5FF` | Active nav item background |
-| `blue200` | `#CCE9FF` | Hover on primary elements |
-| `blue300` | `#A0D2FD` | — |
-| `blue400` | `#62B0F8` | — |
-| `blue500` | `#036FE3` | — |
-| `blue600` | `#0059C8` | **Primary action color** — buttons, links, active icons |
-| `blue700` | `#0044A8` | Pressed state |
-| `blue800` | `#003080` | — |
-| `blue900` | `#002A8E` | — |
-
-### Green (Positive)
-
-| Token | Hex | Common use |
-|---|---|---|
-| `green100` | `#EAF9E8` | Environment switcher background |
-| `green300` | `#9ED696` | Environment type indicator strip |
-| `green400` | `#5DB057` | Environment switcher border |
-| `green600` | `#006D23` | Published status, success text |
-| `green700` | `#00550C` | Environment switcher text |
-
-### Red (Negative)
-
-| Token | Hex | Common use |
-|---|---|---|
-| `red100` | `#FFF2F2` | Error field background |
-| `red600` | `#BD002A` | Error text, destructive button |
-| `red700` | `#9A0020` | Pressed destructive state |
-
-### Orange (Warning)
-
-| Token | Hex | Common use |
-|---|---|---|
-| `orange100` | `#FFF2E4` | Warning note background |
-| `orange400` | `#F07C00` | Warning icons |
-| `orange500` | `#CC4500` | Draft/unpublished state, warning text |
-
-### Purple (Premium — use sparingly)
-
-| Token | Hex | Common use |
-|---|---|---|
-| `purple100` | `#F7F2FF` | Premium feature background |
-| `purple600` | `#8553E7` | Premium label, "new feature" highlight |
-
-### Yellow (last resort only)
-
-| Token | Hex | Note |
-|---|---|---|
-| `yellow400` | `#FFC835` | Only when all other options fail |
-
-### Absolute
-
-| Token | Hex |
-|---|---|
-| `colorWhite` | `#FFFFFF` |
-| `colorBlack` | `#0C141C` |
-
----
-
-## Spacing Tokens
-
-Components carry no external margin. Use these to create space between elements.
-
-| Token | Value | Rem |
-|---|---|---|
-| `spacing2Xs` | 4px | 0.25rem |
-| `spacingXs` | 8px | 0.5rem |
-| `spacingS` | 12px | 0.75rem |
-| `spacingM` | 16px | 1rem |
-| `spacingL` | 24px | 1.5rem |
-| `spacingXl` | 32px | 2rem |
-| `spacing2Xl` | 48px | 3rem |
-| `spacing3Xl` | 64px | 4rem |
-| `spacing4Xl` | 80px | 5rem |
-
-**Usage:**
-```js
-// Inline style
-<div style={{ padding: tokens.spacingM }} />
-
-// Layout component prop
-<Stack spacing="spacingM" />
-<Flex gap="spacingS" />
-```
-
----
-
-## Typography Tokens
-
-### Font Families
-
-| Token | Stack |
-|---|---|
-| `fontStackPrimary` | `Geist Sans, -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial, sans-serif` |
-| `fontStackMonospace` | `Geist Mono, SFMono-Regular, Consolas, Liberation Mono, Menlo, monospace` |
-
-Geist is loaded from `https://cdn.f36.contentful.com`. Always use `fontStackPrimary` — never hardcode `Geist` alone without the fallback stack.
-
-### Font Sizes
-
-| Token | Value | Use |
-|---|---|---|
-| `fontSize4Xl` | 3rem | Hero display text |
-| `fontSize3Xl` | 2.25rem | Large display |
-| `fontSize2Xl` | 1.5rem | Page-level headings |
-| `fontSizeXl` | 1.25rem | Section headings |
-| `fontSizeL` | 1rem | Large body |
-| `fontSizeM` | 0.875rem | **Default body** — most interface text |
-| `fontSizeS` | 0.75rem | Captions, metadata, section labels |
-
-### Font Weights
-
-| Token | Value | Use |
-|---|---|---|
-| `fontWeightNormal` | 400 | All body text |
-| `fontWeightMedium` | 500 | Emphasized labels, active states |
-| `fontWeightDemiBold` | 600 | Headings, section titles, nav group labels |
-
-### Line Heights
-
-| Token | Value | Use |
-|---|---|---|
-| `lineHeightDefault` | 1.5 | Body text |
-| `lineHeightCondensed` | 1.25 | Nav items, badges, compact UI |
-
-### Letter Spacing
-
-| Token | Value |
-|---|---|
-| `letterSpacingDefault` | 0rem |
-| `letterSpacingWide` | 0.1rem |
-
-Forma 36 uses `0` letter spacing by default. Do not add tracking to Geist.
-
----
-
-## Shadow Tokens
-
-| Name | CSS Value | Use |
-|---|---|---|
-| `shadowDefault` | `0 0 0 1px rgba(25,37,50,.10), 0 3px 7px -3px rgba(25,37,50,.10), 0 6px 12px -2px rgba(25,37,50,.10)` | Panels, sidebar, content area, cards |
-| `shadowButton` | `0 1px 0 rgba(17,27,43,.05)` | Secondary and transparent buttons |
-
-Only these two shadows exist in Forma 36. Do not invent custom shadows.
-
----
-
-## Border Radius Tokens
-
-| Token | Value | Use |
-|---|---|---|
-| `borderRadiusSmall` | 4px | Nav items, badges, small chips |
-| `borderRadiusMedium` | 6px | Buttons, inputs, menus |
-| `borderRadiusLarge` | 12px | Panels, cards, modals |
-| `borderRadiusPill` | 100px | Avatars, pill badges |
-
-Top-only radius (panels flush to bottom edge): apply `border-radius: 12px 12px 0 0`.
-
----
-
-## Z-Index Tokens
-
-| Token | Value | Use |
-|---|---|---|
-| `zIndexDefault` | 0 | Normal flow |
-| `zIndexSticky` | 101 | Sticky headers |
-| `zIndexDropdown` | 200 | Menus, dropdowns |
-| `zIndexModal` | 1000 | Modals, dialogs |
-| `zIndexNotification` | 9000 | Toast notifications |

From 75916e4be162357f991ac72612c51ea351b347fa Mon Sep 17 00:00:00 2001
From: toniwowtscherk <toni.wowtscherk@contentful.com>
Date: Mon, 27 Apr 2026 17:01:55 +0200
Subject: [PATCH 09/13] fix: address source validation and PR review feedback
 for Forma 36 skill

Source validation against forma-36 repo:
- Fix 38 wrong icon names (Phosphor naming convention)
- Fix 3 shadow token names and 1 color value
- Restore Skeleton.Row component

PR review comment fixes:
- Use Emotion css prop instead of inline styles
- Add missing component props (Table, Card, Accordion, Skeleton, Pagination, List)
- Fix Button docs (token names, writing rules, isActive, navigation)
- Rename confirmation-dialog to confirmation-modal
- Fix Badge examples to not use entity status labels
- Add code-connect.md guide

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 skills/SKILL.md                               | 263 ++++++++++++---
 ...tion-dialog.tsx => confirmation-modal.tsx} |  25 +-
 skills/examples/detail-page.tsx               |  10 +-
 skills/examples/error-state.tsx               |  25 +-
 skills/examples/form-page.tsx                 |  13 +-
 skills/examples/list-page.tsx                 |  29 +-
 skills/examples/settings-page.tsx             |  31 +-
 skills/guidelines/code-connect.md             | 311 ++++++++++++++++++
 skills/guidelines/components/buttons.md       |  84 ++---
 skills/guidelines/components/data-display.md  | 103 ++++--
 skills/guidelines/components/feedback.md      |  59 ++--
 skills/guidelines/components/forms.md         |  63 ++--
 skills/guidelines/components/layout.md        | 113 ++++---
 skills/guidelines/components/navigation.md    |  61 ++--
 skills/guidelines/components/overview.md      |  88 ++---
 skills/guidelines/components/utility.md       |  62 ++--
 skills/guidelines/composition/base-shell.md   |  14 +-
 .../guidelines/composition/screen-patterns.md |  42 ++-
 skills/guidelines/foundations/icons.md        |  91 ++++-
 skills/guidelines/foundations/writing.md      |  40 +--
 skills/guidelines/setup.md                    |   8 +-
 skills/guidelines/tokens/color.md             | 117 +++----
 skills/guidelines/tokens/effects.md           |  78 ++---
 skills/guidelines/tokens/overview.md          |  13 +-
 skills/guidelines/tokens/spacing.md           |  40 +--
 skills/guidelines/tokens/typography.md        |  76 ++---
 26 files changed, 1309 insertions(+), 550 deletions(-)
 rename skills/examples/{confirmation-dialog.tsx => confirmation-modal.tsx} (63%)
 create mode 100644 skills/guidelines/code-connect.md

diff --git a/skills/SKILL.md b/skills/SKILL.md
index f0a6eac0b6..b91d55c183 100644
--- a/skills/SKILL.md
+++ b/skills/SKILL.md
@@ -2,9 +2,10 @@
 name: forma36
 description: >
   Forma 36 — Contentful's design system. Tokens, components, composition patterns,
-  writing rules, and reference implementations for AI agents building Contentful UI.
+  writing rules, Code Connect mappings, and reference implementations for AI agents building Contentful UI.
   Use when the user references Forma 36, f36, Contentful components, or wants to
-  build a Contentful app UI.
+  build a Contentful app UI — including prototypes, screens, and interface explorations.
+  Also powers the Forma 36 Figma Make Kit guidelines.
 ---
 
 # Forma 36 — Contentful Design System
@@ -13,20 +14,36 @@ Forma 36 is the design language of Contentful. Every screen, component, and inte
 
 **Docs:** https://f36.contentful.com
 **Source:** https://github.com/contentful/forma-36
+**Figma Components:** https://www.figma.com/design/BDteZSphg3YPJTMlABQozc/Forma-36-Components
+**Figma Icons/Assets:** https://www.figma.com/design/ILoICAP1fxyvE7xmpWiJBi/Forma-36-Assets
+
+---
+
+## Pre-flight checklist — VERIFY before generating ANY code
+
+```
+REQUIRED  import '@contentful/f36-components/dist/styles.css'  — without this, all components render unstyled
+REQUIRED  Every component has an explicit import from @contentful/f36-components or @contentful/f36-icons
+REQUIRED  All icon names come from @contentful/f36-icons (Phosphor set) — see guidelines/foundations/icons.md for the approved list. NEVER invent icon names. Common: DotsThreeIcon (menus), TrashSimpleIcon (delete), PencilSimpleIcon (edit), GearSixIcon (settings), PlusIcon, MagnifyingGlassIcon (search), XIcon (close), CheckIcon, WarningIcon, ArrowLeftIcon.
+REQUIRED  All colors, spacing, typography use @contentful/f36-tokens — NEVER hardcode hex, px, or font stacks
+REQUIRED  Use Layout (not Workbench) as the page shell. Layout.Header, Layout.Body, Layout.Sidebar are REAL compound sub-components (verified in source) — use them confidently. These are the ONLY valid sub-components.
+REQUIRED  Skeleton sub-components: Skeleton.Container, Skeleton.DisplayText, Skeleton.BodyText, Skeleton.Image, Skeleton.Row (for table loading: rowCount, columnCount props). There is no Skeleton.Table or Skeleton.Cell.
+```
 
 ---
 
 ## Choose your path
 
-This skill serves two audiences. Pick the one that matches your task, then follow its reading order.
+This skill serves five workflows. Pick the one that matches your task, then follow its reading order.
 
-### Path A — Designer prototyping
+### Path A — Designer prototyping (no Figma URL)
 
-You are designing a screen, vibe-coding a prototype, or exploring a UI concept in Figma Make. You care about how it *looks and feels* — layout, visual language, screen structure, copy.
+You are designing a screen, vibe-coding a prototype, or exploring a UI concept. You care about how it _looks and feels_ — layout, visual language, screen structure, copy.
 
 **Figma Make Kit:** https://www.figma.com/make/jcC82kTLl5yz6W9Mk1LJF8/Forma-36-Kit
 
 **Reading order:**
+
 1. `guidelines/overview.md` — Design philosophy and critical rules
 2. `guidelines/composition/base-shell.md` — The app chrome you must always use
 3. `guidelines/composition/screen-patterns.md` — Pick the pattern closest to your screen
@@ -41,11 +58,12 @@ You are designing a screen, vibe-coding a prototype, or exploring a UI concept i
 **Skim:** Individual component prop tables — reference them only when you need a specific detail.
 **Use examples as:** Starting templates to fork and adapt.
 
-### Path B — Developer implementing
+### Path B — Developer implementing (no Figma URL)
 
 You are writing production code, building a Contentful app, or implementing a design spec. You need exact prop names, token values, correct import paths, and API precision.
 
 **Reading order:**
+
 1. `guidelines/overview.md` — Critical rules (memorize these)
 2. `guidelines/setup.md` — Dependencies, CSS import, font loading
 3. `guidelines/tokens/` — Read all token files. Every value you use must come from here.
@@ -59,12 +77,131 @@ You are writing production code, building a Contentful app, or implementing a de
 **Skim:** Composition overview and writing guidelines — reference them for structure and copy decisions.
 **Use examples as:** API reference and correctness checks.
 
+### Path C — Figma design to code (Figma URL provided)
+
+A Figma URL is present. The goal is to translate Figma designs into production code using the correct Forma 36 components with their exact props, tokens, and patterns.
+
+**How this works:**
+
+1. Use the Figma MCP server to call `get_design_context` with the Figma URL's `fileKey` and `nodeId`
+2. The response will include **Code Connect snippets** for any Forma 36 component that has a published mapping — these tell you exactly which `@contentful/f36-components` or `@contentful/f36-icons` import to use
+3. Cross-reference Code Connect snippets with the component files in `guidelines/components/` for full prop tables and constraints
+4. Use `guidelines/tokens/` to map any remaining design values (colors, spacing, typography) to token names
+5. Follow `guidelines/composition/screen-patterns.md` for the page structure
+
+**Reading order:**
+
+1. Fetch design context via MCP — read the Code Connect snippets first
+2. `guidelines/code-connect.md` — Reference for Figma→code property mappings when Code Connect snippets are ambiguous
+3. `guidelines/components/<relevant-file>.md` — Full prop tables for each connected component
+4. `guidelines/tokens/` — Map remaining design values to tokens
+5. `guidelines/composition/screen-patterns.md` — Verify page structure
+6. `guidelines/foundations/accessibility.md` — Ensure ARIA labels and focus management
+
+**Key principle:** When a Code Connect snippet is available, trust it — it maps the Figma component's exact variant properties to the correct React props. Use the component reference files only for props not covered by Code Connect (event handlers, children, complex composition).
+
+**Code Connect coverage:**
+
+- **48 components** connected in the Forma 36 Components Figma file
+- **239 icons** connected in the Forma 36 Assets Figma file
+- See `guidelines/code-connect.md` for the complete mapping table
+
+### Path D — Code to Figma design (writing to Figma via MCP)
+
+You have existing code, a running prototype, or a component implementation and want to push it into a Figma file as a design. This uses the Figma MCP server's write capabilities.
+
+**Prerequisites:**
+
+- Figma MCP server connected (remote `mcp.figma.com` or local `127.0.0.1:3845/mcp`)
+- Load the `figma-use` skill **before every `use_figma` call** — mandatory, skipping it causes hard-to-debug failures
+- For full-page layouts, also load the `figma-generate-design` skill
+
+**How this works:**
+
+1. Read the source code to understand what components, tokens, and layout patterns are used
+2. Use `search_design_system` via MCP to discover matching Forma 36 Figma components, variables, and styles in the target file's libraries
+3. Map React props back to Figma component properties using `guidelines/code-connect.md` in reverse — e.g. `variant="primary"` on `<Button>` means set Figma property "Type" to "Primary"
+4. Build the design in Figma section-by-section using `use_figma`, importing library components rather than drawing raw shapes
+5. Bind Figma variables (color, spacing, typography) instead of hardcoding values — this keeps the design connected to the design system
+
+**Reading order:**
+
+1. Read the source code — identify all Forma 36 components, tokens, and screen pattern used
+2. `guidelines/code-connect.md` — Use the mapping table **in reverse** (React prop -> Figma property name) to set correct variant properties on Figma components
+3. `guidelines/tokens/color.md` + `guidelines/tokens/spacing.md` — Know which token values to bind as Figma variables
+4. `guidelines/composition/base-shell.md` — Replicate the app chrome faithfully in the Figma frame
+5. Load `figma-use` skill — required Plugin API reference for every `use_figma` call
+6. Load `figma-generate-design` skill — for multi-section page assembly workflow
+
+**Key principles:**
+
+- **Use library components, not raw shapes.** Call `search_design_system` to find the published Forma 36 component, then create an instance. Never recreate a Button from rectangles and text.
+- **Reverse the Code Connect table.** If the code says `<Button variant="primary" size="small">`, set Figma properties `Type=Primary`, `Size=Small (default)` on the component instance.
+- **Bind variables, don't hardcode.** Map `tokens.spacingM` to the corresponding Figma spacing variable, `tokens.blue600` to the color variable. This keeps the design token-connected.
+- **Build incrementally.** For full pages, assemble section-by-section — header first, then sidebar, then content area — verifying each section via `get_screenshot` before moving on.
+- **Match the real layout.** Use auto-layout in Figma to mirror the Flex/Stack/Grid structure in code. A `<Stack flexDirection="column" spacing="spacingM">` becomes a vertical auto-layout frame with `itemSpacing=16`.
+
+**When to use this path vs. `figma-capture-to-file`:**
+
+- Use **Path D** when you want an editable, token-connected, component-based Figma design that designers can iterate on
+- Use **`figma-capture-to-file`** when you just need a flat screenshot of a running localhost dropped into a Figma frame
+
+### Path E — Edit existing Figma design (modify a frame on canvas)
+
+A designer points to an existing Figma frame (via URL or desktop selection) and asks for changes — swap a variant, adjust layout, add a component, rearrange sections, update copy, or restyle an element. The design already exists; you are modifying it in place.
+
+**Prerequisites:**
+
+- Figma MCP server connected (remote `mcp.figma.com` or local `127.0.0.1:3845/mcp`)
+- Load the `figma-use` skill **before every `use_figma` call** — mandatory
+
+**How this works:**
+
+1. Fetch the current state of the frame using `get_design_context` or `get_screenshot` to understand what's already there
+2. Identify the specific nodes that need to change — use `get_metadata` or the Plugin API via `use_figma` to walk the layer tree
+3. Make targeted edits using `use_figma` — change properties, swap component instances, reorder children, update text, adjust auto-layout settings
+4. Verify each edit with `get_screenshot` before moving to the next change
+5. Use `guidelines/code-connect.md` to ensure any component property changes use correct Figma property names (e.g., set "Type" not "Variant")
+
+**Reading order:**
+
+1. Fetch the design — `get_design_context` or `get_screenshot` to see the current state
+2. `guidelines/code-connect.md` — Reference the Figma property names when changing component variants (the "Figma prop" column is what you set on the canvas)
+3. `guidelines/tokens/` — When changing colors, spacing, or typography, bind to Figma variables matching the token names
+4. `guidelines/composition/screen-patterns.md` — If restructuring a page, verify the result still follows the correct pattern
+5. `guidelines/foundations/writing.md` — If updating copy, follow the writing rules (sentence case, verb-first labels, "Never mind")
+6. Load `figma-use` skill — required before every `use_figma` call
+
+**Key principles:**
+
+- **Read, log, then write.** Always fetch current state AND return current property values before overwriting. Use a read-only `use_figma` call that returns `{ before: { componentProperties, text, fills } }`, then a separate write call. See `guidelines/code-connect.md` for the pattern.
+- **Edit surgically.** Change only what was requested. Don't reorganize layers, rename nodes, or "clean up" the design unless asked.
+- **Preserve component instances.** When swapping a variant, change the property on the existing instance — don't detach it and rebuild.
+- **Use Figma property names, not React names.** On the canvas, it's "Type" not "variant", "Small (default)" not "small". The Code Connect table's "Figma prop" column is your reference.
+- **Verify after EVERY edit.** Call `get_screenshot` MCP tool after each `use_figma` write. This is mandatory, not optional. Do not skip this step.
+- **Respect auto-layout.** If a frame uses auto-layout, work within it — add children, change spacing, adjust padding. Don't switch to absolute positioning unless the designer explicitly asks.
+
+**Common edit operations:**
+
+- Change a component variant: set the Figma property (e.g., `Type=Negative` on a Button instance)
+- Update text content: find the text node and set `characters`
+- Add a component: use `search_design_system` to find it, create instance, insert into the target frame
+- Reorder items: move child nodes within their parent's `children` array
+- Adjust spacing: change `itemSpacing` on an auto-layout frame, or `paddingTop`/`paddingBottom`/etc.
+- Swap an icon: find the icon instance, swap its component to a different one from the library
+
+**When to use Path E vs. Path D:**
+
+- Use **Path E** when a design already exists and needs modification
+- Use **Path D** when creating a new design from scratch based on code
+
 ---
 
 ## Critical rules
 
-These apply to both paths. Do not override them.
+These apply to all paths. Do not override them.
 
+- **CSS import is REQUIRED** — every file must include `import '@contentful/f36-components/dist/styles.css';`. Without it, all components render unstyled. This is the #1 most-forgotten rule.
 - **Tokens only** — never hardcode hex colors, pixel values, or font stacks. Always use `@contentful/f36-tokens`.
 - **Sentence case** — all labels, headings, buttons, menu items. Never Title Case or ALL CAPS.
 - **One primary button** per screen section maximum.
@@ -74,7 +211,7 @@ These apply to both paths. Do not override them.
 - **Phosphor icons only** — never Material, Heroicons, Feather, or Lucide.
 - **"Never mind"** — the cancel label for destructive confirmations. Not "Cancel".
 - **`Layout` not `Workbench`** — Workbench is deprecated.
-- **No custom shadows** — only `shadowDefault`, `shadowHeavy`, `shadowButton`, `insetBoxShadowDefault`.
+- **No custom shadows** — only `boxShadowDefault`, `boxShadowHeavy`, `boxShadowPositive`, `insetBoxShadowDefault`.
 - **No border radius outside the scale** — 4px, 6px, 12px, 100px only.
 
 ---
@@ -109,67 +246,99 @@ Font: Geist from `https://cdn.f36.contentful.com`. Apply `font-feature-settings:
 
 ---
 
+## Forma 36 Make Kit
+
+The Forma 36 Make Kit is published to Figma's cloud and consumed by Figma Make at:
+**https://www.figma.com/make/jcC82kTLl5yz6W9Mk1LJF8/Forma-36-Kit**
+
+The authoring source lives locally at `Forma 36 Make Kit/` in the workspace root.
+
+### Relationship between this skill and the Make Kit
+
+- **This skill** is the reference for **Claude Code** when building prototypes and implementing designs.
+- **The Make Kit** (`guidelines/` + `examples/`) is the reference for **Figma Make** — the same design system knowledge restructured for Figma Make's progressive disclosure pattern.
+- Both contain the same design system rules. When editing one, keep the other in sync.
+
+---
+
 ## File map
 
 Each folder contains an `overview.md` that indexes its contents.
 
 ### `guidelines/`
 
-| File | What it covers |
-|---|---|
-| `overview.md` | Design philosophy, product character, critical rules |
-| `setup.md` | Dependencies, CSS import, Geist font, token imports, icon library |
+| File              | What it covers                                                                                               |
+| ----------------- | ------------------------------------------------------------------------------------------------------------ |
+| `overview.md`     | Design philosophy, product character, critical rules                                                         |
+| `setup.md`        | Dependencies, CSS import, Geist font, token imports, icon library                                            |
+| `code-connect.md` | Complete Figma Code Connect mapping — 48 connected components + 239 icons with verified Figma property names |
 
 ### `guidelines/tokens/`
 
-| File | What it covers |
-|---|---|
-| `overview.md` | Token philosophy and index |
-| `color.md` | Semantic colors, gray scale, blue/green/red/orange/purple/yellow palettes |
+| File            | What it covers                                                                    |
+| --------------- | --------------------------------------------------------------------------------- |
+| `overview.md`   | Token philosophy and index                                                        |
+| `color.md`      | Semantic colors, gray scale, blue/green/red/orange/purple/yellow palettes         |
 | `typography.md` | Font families, sizes, weights, line heights, letter spacing, composite type roles |
-| `spacing.md` | 4px–80px spacing scale, content width tokens |
-| `effects.md` | Shadows (4 only), focus rings, border radius, z-index, transitions |
+| `spacing.md`    | 4px-80px spacing scale, content width tokens                                      |
+| `effects.md`    | Shadows (4 only), focus rings, border radius, z-index, transitions                |
 
 ### `guidelines/components/`
 
-| File | What it covers |
-|---|---|
-| `overview.md` | Component decision tree and file index |
-| `layout.md` | `Box`, `Flex`, `Stack`, `Grid`, `Layout` |
-| `buttons.md` | `Button` (5 variants), `IconButton`, `TextLink`, `CopyButton` |
-| `forms.md` | `FormControl`, `TextInput`, `Textarea`, `Select`, `Autocomplete`, `Multiselect`, `Checkbox`, `Radio`, `Switch`, `DatePicker` |
-| `feedback.md` | `Notification`, `Note`, `Badge`, `EntityStatusBadge`, `Spinner` |
-| `navigation.md` | `Tabs`, `Modal`, `Menu`, `Tooltip`, `Popover`, `NavList` |
-| `data-display.md` | `Table`, `Card`, `EntityList`, `Accordion`, `Collapse`, `Skeleton`, `Pagination`, `List`, `ProgressStepper` |
-| `content-media.md` | `Asset`, `Avatar`, `Image`, `DateTime`, `UsageCard` |
-| `utility.md` | Typography components, `Header`, `DragHandle`, `Pill`, Icons |
+| File               | What it covers                                                                                                               |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
+| `overview.md`      | Component decision tree and file index                                                                                       |
+| `layout.md`        | `Box`, `Flex`, `Stack`, `Grid`, `Layout`                                                                                     |
+| `buttons.md`       | `Button` (5 variants), `IconButton`, `TextLink`, `CopyButton`                                                                |
+| `forms.md`         | `FormControl`, `TextInput`, `Textarea`, `Select`, `Autocomplete`, `Multiselect`, `Checkbox`, `Radio`, `Switch`, `DatePicker` |
+| `feedback.md`      | `Notification`, `Note`, `Badge`, `EntityStatusBadge`, `Spinner`                                                              |
+| `navigation.md`    | `Tabs`, `Modal`, `Menu`, `Tooltip`, `Popover`, `NavList`                                                                     |
+| `data-display.md`  | `Table`, `Card`, `EntityList`, `Accordion`, `Collapse`, `Skeleton`, `Pagination`, `List`, `ProgressStepper`                  |
+| `content-media.md` | `Asset`, `Avatar`, `Image`, `DateTime`, `UsageCard`                                                                          |
+| `utility.md`       | Typography components, `Header`, `DragHandle`, `Pill`, Icons                                                                 |
 
 ### `guidelines/composition/`
 
-| File | What it covers |
-|---|---|
-| `overview.md` | Composition philosophy and file index |
-| `base-shell.md` | Standard app chrome — top bar (52px), sidebar (240px), content area |
+| File                 | What it covers                                                                                      |
+| -------------------- | --------------------------------------------------------------------------------------------------- |
+| `overview.md`        | Composition philosophy and file index                                                               |
+| `base-shell.md`      | Standard app chrome — top bar (52px), sidebar (240px), content area                                 |
 | `screen-patterns.md` | 9 named patterns: list, detail, settings, empty state, error, confirmation, wizard, dashboard, form |
 
 ### `guidelines/foundations/`
 
-| File | What it covers |
-|---|---|
-| `overview.md` | Foundations index |
-| `writing.md` | Voice & tone, sentence case, button labels, error messages, forbidden phrases, status labels |
-| `icons.md` | Phosphor library, Regular vs Duotone, sizing (14/16/20px), color-by-role |
-| `accessibility.md` | WCAG contrast, keyboard navigation, ARIA labels, screen reader guidance, focus rings |
+| File               | What it covers                                                                               |
+| ------------------ | -------------------------------------------------------------------------------------------- |
+| `overview.md`      | Foundations index                                                                            |
+| `writing.md`       | Voice & tone, sentence case, button labels, error messages, forbidden phrases, status labels |
+| `icons.md`         | Phosphor library, Regular vs Duotone, sizing (14/16/20px), color-by-role                     |
+| `accessibility.md` | WCAG contrast, keyboard navigation, ARIA labels, screen reader guidance, focus rings         |
 
 ### `examples/`
 
 Working TSX files demonstrating correct usage. Each maps to a screen pattern.
 
-| File | Pattern | What it shows |
-|---|---|---|
-| `list-page.tsx` | List / Index | Table, search, EntityStatusBadge, Menu actions, Pagination, empty state, Skeleton |
-| `detail-page.tsx` | Detail / Edit | Right sidebar, breadcrumbs, form validation, unsaved-changes Note |
-| `settings-page.tsx` | Settings | Grouped sections, Switch toggles, danger zone |
-| `confirmation-dialog.tsx` | Confirmation | Modal, "Never mind" cancel, `isLoading` confirm, `shouldCloseOnOverlayClick={false}` |
-| `form-page.tsx` | Standalone Form | `Layout variant="narrow"`, grouped FormControls, Accordion, Notification |
-| `error-state.tsx` | Error State | Centered error, WarningOctagonIcon, "Try again" + "Go back" |
+| File                     | Pattern         | What it shows                                                                        |
+| ------------------------ | --------------- | ------------------------------------------------------------------------------------ |
+| `list-page.tsx`          | List / Index    | Table, search, EntityStatusBadge, Menu actions, Pagination, empty state, Skeleton    |
+| `detail-page.tsx`        | Detail / Edit   | Right sidebar, breadcrumbs, form validation, unsaved-changes Note                    |
+| `settings-page.tsx`      | Settings        | Grouped sections, Switch toggles, danger zone                                        |
+| `confirmation-modal.tsx` | Confirmation    | Modal, "Never mind" cancel, `isLoading` confirm, `shouldCloseOnOverlayClick={false}` |
+| `form-page.tsx`          | Standalone Form | `Layout variant="narrow"`, grouped FormControls, Accordion, Notification             |
+| `error-state.tsx`        | Error State     | Centered error, WarningOctagonIcon, "Try again" + "Go back"                          |
+
+---
+
+## Post-flight checklist — VERIFY before returning code to the user
+
+```
+CHECK  CSS import present: import '@contentful/f36-components/dist/styles.css'
+CHECK  Every color, spacing, and font value comes from @contentful/f36-tokens — no hardcoded hex, px, or font stacks
+CHECK  Every icon name exists in @contentful/f36-icons — see guidelines/foundations/icons.md. If unsure, DON'T guess.
+CHECK  Every input is inside a FormControl with a Label
+CHECK  Only ONE primary button per visible screen section
+CHECK  All labels and headings use sentence case — never Title Case or ALL CAPS
+CHECK  Destructive confirmation cancel label is "Never mind" — not "Cancel"
+CHECK  No usage of Workbench — use Layout instead
+CHECK  No fabricated sub-components: Layout only has Layout.Header, Layout.Body, Layout.Sidebar. Skeleton only has Skeleton.Container, Skeleton.DisplayText, Skeleton.BodyText, Skeleton.Image.
+```
diff --git a/skills/examples/confirmation-dialog.tsx b/skills/examples/confirmation-modal.tsx
similarity index 63%
rename from skills/examples/confirmation-dialog.tsx
rename to skills/examples/confirmation-modal.tsx
index 24f1f3a5cf..5f54c1a24a 100644
--- a/skills/examples/confirmation-dialog.tsx
+++ b/skills/examples/confirmation-modal.tsx
@@ -1,11 +1,9 @@
-/**
- * Confirmation Dialog — destructive action pattern.
- * Title and confirm button always match. Cancel is "Never mind".
- */
+// REQUIRED: CSS import — without this, all components render unstyled
+import '@contentful/f36-components/dist/styles.css';
 import { Modal, Button, Paragraph } from '@contentful/f36-components';
 import { useState } from 'react';
 
-function DeleteContentTypeDialog() {
+function DeleteContentTypeModal() {
   const [isOpen, setIsOpen] = useState(false);
   const [isDeleting, setIsDeleting] = useState(false);
 
@@ -28,17 +26,26 @@ function DeleteContentTypeDialog() {
         size="small"
         shouldCloseOnOverlayClick={false}
       >
-        <Modal.Header title="Delete content type" onClose={() => setIsOpen(false)} />
+        <Modal.Header
+          title="Delete content type"
+          onClose={() => setIsOpen(false)}
+        />
         <Modal.Content>
           <Paragraph>
-            This content type and all its fields will be permanently deleted. This cannot be undone.
+            This content type and all its fields will be permanently deleted.
+            This cannot be undone.
           </Paragraph>
         </Modal.Content>
         <Modal.Controls>
+          {/* Cancel label MUST be "Never mind" for destructive confirmations — never "Cancel" */}
           <Button variant="secondary" onClick={() => setIsOpen(false)}>
             Never mind
           </Button>
-          <Button variant="negative" isLoading={isDeleting} onClick={handleDelete}>
+          <Button
+            variant="negative"
+            isLoading={isDeleting}
+            onClick={handleDelete}
+          >
             Delete content type
           </Button>
         </Modal.Controls>
@@ -47,4 +54,4 @@ function DeleteContentTypeDialog() {
   );
 }
 
-export { DeleteContentTypeDialog };
+export { DeleteContentTypeModal };
diff --git a/skills/examples/detail-page.tsx b/skills/examples/detail-page.tsx
index 8e9e44923b..8fb9267f84 100644
--- a/skills/examples/detail-page.tsx
+++ b/skills/examples/detail-page.tsx
@@ -1,6 +1,5 @@
-/**
- * Detail / Edit Page — single entity view with right sidebar.
- */
+// REQUIRED: CSS import — without this, all components render unstyled
+import '@contentful/f36-components/dist/styles.css';
 import {
   Layout,
   Header,
@@ -62,7 +61,10 @@ function EntryDetailPage() {
 
           <FormControl>
             <FormControl.Label>Description</FormControl.Label>
-            <Textarea rows={4} defaultValue="Main promotional banner for the homepage." />
+            <Textarea
+              rows={4}
+              defaultValue="Main promotional banner for the homepage."
+            />
             <FormControl.HelpText>
               A short description displayed below the banner title.
             </FormControl.HelpText>
diff --git a/skills/examples/error-state.tsx b/skills/examples/error-state.tsx
index 060a741f94..56589e84c4 100644
--- a/skills/examples/error-state.tsx
+++ b/skills/examples/error-state.tsx
@@ -1,7 +1,12 @@
-/**
- * Error State — full-page error with recovery action.
- */
-import { Flex, Heading, Paragraph, Button, Stack } from '@contentful/f36-components';
+// REQUIRED: CSS import — without this, all components render unstyled
+import '@contentful/f36-components/dist/styles.css';
+import {
+  Flex,
+  Heading,
+  Paragraph,
+  Button,
+  Stack,
+} from '@contentful/f36-components';
 import { WarningOctagonIcon } from '@contentful/f36-icons';
 import tokens from '@contentful/f36-tokens';
 
@@ -12,15 +17,21 @@ function PageError({ section = 'content types' }: { section?: string }) {
       alignItems="center"
       justifyContent="center"
       padding="spacing2Xl"
-      style={{ minHeight: '400px' }}
+      css={{ minHeight: '400px' }}
     >
       <WarningOctagonIcon
         size="medium"
-        style={{ width: '48px', height: '48px', color: tokens.red600, marginBottom: tokens.spacingM }}
+        css={{
+          width: '48px',
+          height: '48px',
+          color: tokens.red600,
+          marginBottom: tokens.spacingM,
+        }}
       />
       <Heading marginBottom="spacingXs">Couldn't load {section}</Heading>
       <Paragraph marginBottom="spacingL">
-        Something went wrong while loading this page. Check your connection and try again.
+        Something went wrong while loading this page. Check your connection and
+        try again.
       </Paragraph>
       <Stack spacing="spacingS">
         <Button variant="primary" onClick={() => window.location.reload()}>
diff --git a/skills/examples/form-page.tsx b/skills/examples/form-page.tsx
index 0b9e1e6dcb..b4ce4ddbfd 100644
--- a/skills/examples/form-page.tsx
+++ b/skills/examples/form-page.tsx
@@ -1,6 +1,5 @@
-/**
- * Standalone Form Page — narrow layout, grouped fields, inline validation.
- */
+// REQUIRED: CSS import — without this, all components render unstyled
+import '@contentful/f36-components/dist/styles.css';
 import {
   Layout,
   Header,
@@ -45,7 +44,6 @@ function CreateContentTypePage() {
     >
       <Layout.Body>
         <Stack flexDirection="column" spacing="spacingXl">
-          {/* Basic info */}
           <Stack flexDirection="column" spacing="spacingM">
             <Heading>Basic information</Heading>
 
@@ -67,11 +65,13 @@ function CreateContentTypePage() {
 
             <FormControl>
               <FormControl.Label>Description</FormControl.Label>
-              <Textarea rows={3} placeholder="Describe what this content type is for" />
+              <Textarea
+                rows={3}
+                placeholder="Describe what this content type is for"
+              />
             </FormControl>
           </Stack>
 
-          {/* Display settings */}
           <Stack flexDirection="column" spacing="spacingM">
             <Heading>Display</Heading>
 
@@ -87,7 +87,6 @@ function CreateContentTypePage() {
             </FormControl>
           </Stack>
 
-          {/* Advanced — collapsed by default */}
           <Accordion>
             <Accordion.Item title="Advanced settings">
               <Stack flexDirection="column" spacing="spacingM">
diff --git a/skills/examples/list-page.tsx b/skills/examples/list-page.tsx
index ceccbcadc0..0c441b0d9b 100644
--- a/skills/examples/list-page.tsx
+++ b/skills/examples/list-page.tsx
@@ -1,7 +1,5 @@
-/**
- * List / Index Page — the most common Contentful screen pattern.
- * Shows a filterable, paginated table of content types.
- */
+// REQUIRED: CSS import — without this, all components render unstyled
+import '@contentful/f36-components/dist/styles.css';
 import {
   Layout,
   Header,
@@ -18,8 +16,14 @@ import {
   Heading,
   Skeleton,
 } from '@contentful/f36-components';
-import { PlusIcon, SearchIcon, MoreHorizontalIcon } from '@contentful/f36-icons';
+// Icons: only from @contentful/f36-icons (Phosphor). DotsThreeIcon for menus, NOT MoreHorizontalIcon.
+import {
+  PlusIcon,
+  MagnifyingGlassIcon,
+  DotsThreeIcon,
+} from '@contentful/f36-icons';
 
+// Layout.Header, Layout.Body, Layout.Sidebar are REAL compound sub-components (verified in source)
 function ContentTypesListPage() {
   return (
     <Layout
@@ -37,7 +41,7 @@ function ContentTypesListPage() {
               <TextInput
                 type="search"
                 placeholder="Search content types"
-                icon={<SearchIcon />}
+                icon={<MagnifyingGlassIcon />}
               />
             }
           />
@@ -67,7 +71,7 @@ function ContentTypesListPage() {
                 <Menu>
                   <Menu.Trigger>
                     <IconButton
-                      icon={<MoreHorizontalIcon />}
+                      icon={<DotsThreeIcon />}
                       aria-label="Actions"
                       variant="transparent"
                       size="small"
@@ -98,9 +102,6 @@ function ContentTypesListPage() {
   );
 }
 
-/**
- * Empty state variant — shown when no content types exist yet.
- */
 function ContentTypesEmptyState() {
   return (
     <Flex
@@ -110,9 +111,11 @@ function ContentTypesEmptyState() {
       padding="spacing2Xl"
       style={{ minHeight: '400px' }}
     >
+      {/* Sentence case: "No content types yet" — never Title Case */}
       <Heading marginBottom="spacingS">No content types yet</Heading>
       <Paragraph marginBottom="spacingL">
-        Content types define the structure of your content. Start by adding your first one.
+        Content types define the structure of your content. Start by adding your
+        first one.
       </Paragraph>
       <Button variant="primary" startIcon={<PlusIcon />}>
         Add content type
@@ -121,9 +124,7 @@ function ContentTypesEmptyState() {
   );
 }
 
-/**
- * Loading state — shown while data is being fetched.
- */
+// Skeleton.Row renders table loading rows (props: rowCount, columnCount)
 function ContentTypesLoading() {
   return (
     <Table>
diff --git a/skills/examples/settings-page.tsx b/skills/examples/settings-page.tsx
index 0aa8a3c9ba..de0eac4acd 100644
--- a/skills/examples/settings-page.tsx
+++ b/skills/examples/settings-page.tsx
@@ -1,6 +1,5 @@
-/**
- * Settings Page — feature configuration with danger zone.
- */
+// REQUIRED: CSS import — without this, all components render unstyled
+import '@contentful/f36-components/dist/styles.css';
 import {
   Layout,
   Header,
@@ -14,6 +13,7 @@ import {
   Note,
   Box,
 } from '@contentful/f36-components';
+// Tokens: ALL colors/spacing/typography from this package — never hardcode hex or px
 import tokens from '@contentful/f36-tokens';
 
 function WebhookSettingsPage() {
@@ -31,7 +31,6 @@ function WebhookSettingsPage() {
     >
       <Layout.Body>
         <Stack flexDirection="column" spacing="spacingXl">
-          {/* General section */}
           <Box>
             <Heading marginBottom="spacingM">General</Heading>
             <Stack flexDirection="column" spacing="spacingM">
@@ -42,7 +41,10 @@ function WebhookSettingsPage() {
 
               <FormControl isRequired>
                 <FormControl.Label>URL</FormControl.Label>
-                <TextInput type="url" defaultValue="https://api.example.com/webhook" />
+                <TextInput
+                  type="url"
+                  defaultValue="https://api.example.com/webhook"
+                />
                 <FormControl.HelpText>
                   The endpoint that receives the webhook payload.
                 </FormControl.HelpText>
@@ -52,13 +54,14 @@ function WebhookSettingsPage() {
                 <FormControl.Label>Content type</FormControl.Label>
                 <Select defaultValue="json">
                   <Select.Option value="json">application/json</Select.Option>
-                  <Select.Option value="form">application/x-www-form-urlencoded</Select.Option>
+                  <Select.Option value="form">
+                    application/x-www-form-urlencoded
+                  </Select.Option>
                 </Select>
               </FormControl>
             </Stack>
           </Box>
 
-          {/* Triggers section */}
           <Box>
             <Heading marginBottom="spacingM">Triggers</Heading>
             <Stack flexDirection="column" spacing="spacingM">
@@ -68,9 +71,17 @@ function WebhookSettingsPage() {
             </Stack>
           </Box>
 
-          {/* Danger zone */}
-          <Box style={{ borderTop: `1px solid ${tokens.gray200}`, paddingTop: tokens.spacingXl }}>
-            <Note variant="negative" title="Danger zone" marginBottom="spacingM">
+          <Box
+            style={{
+              borderTop: `1px solid ${tokens.gray200}`,
+              paddingTop: tokens.spacingXl,
+            }}
+          >
+            <Note
+              variant="negative"
+              title="Danger zone"
+              marginBottom="spacingM"
+            >
               Deleting this webhook is permanent and cannot be undone.
             </Note>
             <Button variant="negative">Delete webhook</Button>
diff --git a/skills/guidelines/code-connect.md b/skills/guidelines/code-connect.md
new file mode 100644
index 0000000000..c76bf73c66
--- /dev/null
+++ b/skills/guidelines/code-connect.md
@@ -0,0 +1,311 @@
+# Figma Code Connect
+
+Forma 36 components are connected to their Figma design components via Code Connect. When a Figma URL is provided, the MCP `get_design_context` tool returns Code Connect snippets that map Figma variant properties directly to React props.
+
+## How to use Code Connect in your workflow
+
+1. **Figma URL provided** — Call `get_design_context` with the `fileKey` and `nodeId` extracted from the URL
+2. **Read the snippets** — The response includes Code Connect snippets showing the exact import and prop mapping for each recognized component
+3. **Trust the snippet** — Code Connect mappings use the verified Figma property names (e.g., "Type" not "Variant"). The snippet gives you the correct React code.
+4. **Fill in the gaps** — Code Connect covers variant props but not event handlers, children content, or complex composition. Use `guidelines/components/` for those.
+
+## Figma files
+
+| File                                                                                           | Key                      | Connected     |
+| ---------------------------------------------------------------------------------------------- | ------------------------ | ------------- |
+| [Forma 36 Components](https://www.figma.com/design/BDteZSphg3YPJTMlABQozc/Forma-36-Components) | `BDteZSphg3YPJTMlABQozc` | 48 components |
+| [Forma 36 Assets (Icons)](https://www.figma.com/design/ILoICAP1fxyvE7xmpWiJBi/Forma-36-Assets) | `ILoICAP1fxyvE7xmpWiJBi` | 239 icons     |
+
+## Important: Figma property names differ from React prop names
+
+Figma uses its own property names in the component panel. These are **case-sensitive** and often differ from what you'd expect. The most common gotcha:
+
+- Figma calls the variant selector **"Type"** — not "Variant"
+- Figma uses values like **"Small (default)"** — not just "Small"
+- Figma uses **"Text"** for tooltip content — not "Content"
+
+The table below shows the exact Figma property names for each component. Use these when writing `.figma.tsx` Code Connect files or when debugging why a mapping isn't working.
+
+---
+
+## Component Code Connect Reference
+
+All components import from `@contentful/f36-components`.
+
+### Buttons & Actions
+
+| Component        | Figma prop | Values                                                          | React prop  |
+| ---------------- | ---------- | --------------------------------------------------------------- | ----------- |
+| **Button**       | `Type`     | Primary, Secondary, Positive, Negative, Transparent             | `variant`   |
+|                  | `Size`     | Small (default), Medium                                         | `size`      |
+|                  | `Loading`  | boolean                                                         | `isLoading` |
+| **IconButton**   | `Type`     | Primary, Secondary, Positive, Negative, Transparent             | `variant`   |
+|                  | `Size`     | Small (default), Medium                                         | `size`      |
+| **TextLink**     | `Type`     | Primary, Secondary, Positive, Negative, White, Muted, Highlight | `variant`   |
+|                  | `Label`    | string                                                          | `children`  |
+| **CopyButton**   | `Size`     | Small, Medium                                                   | `size`      |
+| **ToggleButton** | `Size`     | Small (default), Medium                                         | `size`      |
+|                  | `Label`    | string                                                          | `children`  |
+
+Note: TextLink's Figma value "Highlight" maps to React `variant="premium"`.
+
+### Forms
+
+| Component        | Figma prop       | Values                       | React prop   |
+| ---------------- | ---------------- | ---------------------------- | ------------ |
+| **TextInput**    | `Size`           | Medium, Small                | `size`       |
+|                  | `Disabled`       | True, False                  | `isDisabled` |
+|                  | `Invalid`        | True, False                  | `isInvalid`  |
+| **Textarea**     | `Disabled`       | True, False                  | `isDisabled` |
+|                  | `Invalid`        | True, False                  | `isInvalid`  |
+| **Select**       | `Size`           | Medium, Small                | `size`       |
+|                  | `State`          | Disabled (only mapped value) | `isDisabled` |
+|                  | `Invalid`        | True                         | `isInvalid`  |
+| **Checkbox**     | `Checked`        | boolean                      | `isChecked`  |
+|                  | `Help text`      | string                       | `helpText`   |
+| **Radio**        | _(example-only)_ |                              |              |
+| **Switch**       | `Size`           | Medium, Small                | `size`       |
+|                  | `Checked`        | True, False                  | `isChecked`  |
+|                  | `Disabled`       | True, False                  | `isDisabled` |
+| **Autocomplete** | _(example-only)_ |                              |              |
+| **Multiselect**  | _(example-only)_ |                              |              |
+| **Datepicker**   | _(example-only)_ |                              |              |
+
+### Feedback & Status
+
+| Component             | Figma prop       | Values                                                                    | React prop         |
+| --------------------- | ---------------- | ------------------------------------------------------------------------- | ------------------ |
+| **Badge**             | `Type`           | Primary, Primary filled, Positive, Negative, Warning, Secondary, Featured | `variant`          |
+|                       | `Size`           | Medium, Small                                                             | `size`             |
+| **EntityStatusBadge** | `Status`         | Draft, New, Changed, Published, Archived, Deleted                         | `entityStatus`     |
+|                       | `Size`           | Default, Small                                                            | `size`             |
+| **Note**              | `Type`           | Neutral, Primary, Positive, Warning, Negative                             | `variant`          |
+|                       | `Close button`   | boolean                                                                   | `withCloseButton`  |
+| **Notification**      | `Type`           | Success, Error, Warning                                                   | _(imperative API)_ |
+| **Spinner**           | _(example-only)_ |                                                                           |                    |
+
+### Navigation & Overlays
+
+| Component           | Figma prop       | Values                                | React prop  |
+| ------------------- | ---------------- | ------------------------------------- | ----------- |
+| **Modal**           | `Size`           | Small, Medium, Large, Full width, Zen | `size`      |
+| **Tabs**            | _(example-only)_ |                                       |             |
+| **Tooltip**         | `Placement`      | Top, Right, Bottom, Left              | `placement` |
+|                     | `Text`           | string                                | `content`   |
+| **Menu** (MenuItem) | _(example-only)_ |                                       |             |
+| **NavList**         | _(example-only)_ |                                       |             |
+| **Popover**         | _(example-only)_ |                                       |             |
+
+### Data Display
+
+| Component           | Figma prop       | Values                              | React prop    |
+| ------------------- | ---------------- | ----------------------------------- | ------------- |
+| **Accordion**       | _(example-only)_ |                                     |               |
+| **Card**            | `Margins`        | None, Default, Large                | `padding`     |
+| **AssetCard**       | `Size`           | Small, Default                      | `size`        |
+| **EntryCard**       | _(example-only)_ |                                     |               |
+| **InlineEntryCard** | `Status`         | Draft, Published, Changed, Archived | `status`      |
+| **EntityList**      | _(example-only)_ |                                     |               |
+| **Pagination**      | _(example-only)_ |                                     |               |
+| **Skeleton**        | _(example-only)_ |                                     |               |
+| **ProgressStepper** | `Orientation`    | Horizontal, Vertical                | `orientation` |
+|                     | `Step style`     | Icons, Numbers                      | `stepStyle`   |
+| **Calendar**        | _(example-only)_ |                                     |               |
+
+### Content & Media
+
+| Component       | Figma prop       | Values                             | React prop  |
+| --------------- | ---------------- | ---------------------------------- | ----------- |
+| **Avatar**      | `Type`           | User, App                          | `variant`   |
+|                 | `Size`           | Tiny, Small, Medium, Large         | `size`      |
+| **AvatarGroup** | `Style`          | Stack, Grid                        | _(variant)_ |
+|                 | `Size`           | Small, Medium                      | `size`      |
+| **Asset**       | _(example-only)_ |                                    |             |
+| **UsageCard**   | `Type`           | Usage, Info                        | `variant`   |
+| **UsageCount**  | `Type`           | Consumption, Periodic, Entitlement | `variant`   |
+
+### Layout & Utility
+
+| Component      | Figma prop       | Values                | React prop           |
+| -------------- | ---------------- | --------------------- | -------------------- |
+| **Header**     | _(example-only)_ |                       |                      |
+| **Navbar**     | _(example-only)_ |                       |                      |
+| **DragHandle** | _(example-only)_ |                       |                      |
+| **Pill**       | `Type`           | Idle, Active, Deleted | `variant`            |
+|                | `Drag handle`    | boolean               | `isDraggable`        |
+|                | `Close button`   | boolean               | `onClose` (presence) |
+
+### Typography
+
+| Component          | Figma prop       | Values                         | React prop    |
+| ------------------ | ---------------- | ------------------------------ | ------------- |
+| **Heading**        | `Truncated`      | boolean                        | `isTruncated` |
+| **Subheading**     | `Truncated`      | boolean                        | `isTruncated` |
+| **Paragraph**      | `Truncated`      | boolean                        | `isTruncated` |
+| **DisplayText**    | `Font size`      | Large, Medium, Small (default) | `size`        |
+| **SectionHeading** | _(example-only)_ |                                |               |
+| **Caption**        | _(example-only)_ |                                |               |
+
+---
+
+## Icons Code Connect
+
+All 239 connected icons follow the same pattern:
+
+```tsx
+import { ArrowDownIcon } from '@contentful/f36-icons';
+
+// Figma prop: Size → tiny, small, medium
+<ArrowDownIcon size={props.size} />;
+```
+
+Every icon component maps the Figma **"Size"** property:
+
+- Medium → `"medium"`
+- Small → `"small"`
+- Tiny → `"tiny"`
+
+Icons import from `@contentful/f36-icons`. The naming convention is PascalCase + `Icon` suffix (e.g., `ArrowDownIcon`, `MagnifyingGlassIcon`, `PlusIcon`).
+
+---
+
+## Components NOT connected
+
+These components are not available as Code Connect mappings due to Figma structure limitations:
+
+| Component       | Reason                                                                                                                 |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| **ButtonGroup** | Figma node is an INSTANCE, not a COMPONENT_SET                                                                         |
+| **FormControl** | No single component_set in Figma — it's a composition pattern with sub-components (Label, HelpText, ValidationMessage) |
+| **Radio**       | `.RadioInput` is a private frame (dot-prefixed), not a published COMPONENT_SET                                         |
+| **Textarea**    | `.TextareaField` is a private frame (dot-prefixed), not a published COMPONENT_SET                                      |
+
+For these, use the component reference in `guidelines/components/` directly.
+
+---
+
+## Writing new Code Connect mappings
+
+If you need to create a new `.figma.tsx` mapping file, use this pattern:
+
+```tsx
+import figma from '@figma/code-connect';
+import { ComponentName } from '@contentful/f36-components';
+
+figma.connect(
+  ComponentName,
+  'https://www.figma.com/design/BDteZSphg3YPJTMlABQozc/Forma-36-Components?node-id=XXXX-YYYY',
+  {
+    props: {
+      variant: figma.enum('Type', {
+        // Use exact Figma property name
+        Primary: 'primary',
+        Secondary: 'secondary',
+      }),
+      size: figma.enum('Size', {
+        'Small (default)': 'small', // Include full Figma value text
+        Medium: 'medium',
+      }),
+      isDisabled: figma.boolean('Disabled'),
+      label: figma.string('Label'),
+    },
+    example: (props) => (
+      <ComponentName variant={props.variant} size={props.size}>
+        {props.label}
+      </ComponentName>
+    ),
+  },
+);
+```
+
+**Rules for writing mappings:**
+
+- Always use `get_code_connect_suggestions` MCP tool to inspect actual Figma property names before writing
+- Figma property names are case-sensitive — "Type" not "type"
+- Include the full Figma value text: "Small (default)" not "Small"
+- The node URL must point to a COMPONENT_SET or COMPONENT node, not an INSTANCE or CANVAS
+- Use the `figma-code-connect-components` skill for the full mapping workflow
+
+---
+
+## Figma Plugin API patterns for Forma 36
+
+### Variable binding (Path D — code to Figma)
+
+When creating Figma designs from code, bind design tokens to Figma variables instead of hardcoding values. Use `setBoundVariable` for non-paint properties and `setBoundVariableForPaint` for fills/strokes.
+
+```js
+// 1. Find the variable by name from existing collections
+const collections = await figma.variables.getLocalVariableCollectionsAsync();
+const tokenCollection = collections.find((c) => c.name === 'Tokens');
+const allVarIds = tokenCollection.variableIds;
+
+// Helper: find a variable by name
+async function findVar(name) {
+  for (const id of allVarIds) {
+    const v = await figma.variables.getVariableByIdAsync(id);
+    if (v.name === name || v.name.endsWith('/' + name)) return v;
+  }
+  return null;
+}
+
+// 2. Bind spacing (GAP, PADDING, etc.)
+const spacingM = await findVar('spacingM');
+if (spacingM) {
+  frame.setBoundVariable('itemSpacing', spacingM);
+  frame.setBoundVariable('paddingTop', spacingM);
+  frame.setBoundVariable('paddingBottom', spacingM);
+}
+
+// 3. Bind colors (fills/strokes) — returns a NEW paint, must reassign
+const blue600 = await findVar('blue600');
+if (blue600) {
+  const fills = [...node.fills];
+  const newPaint = figma.variables.setBoundVariableForPaint(
+    fills[0],
+    'color',
+    blue600,
+  );
+  node.fills = [newPaint]; // Must reassign — paint is immutable
+}
+```
+
+### Read-then-write pattern (Path E — edit existing Figma)
+
+Always read current state and log values BEFORE overwriting. This enables rollback and makes edits auditable.
+
+```js
+// Step 1: Read current state and return it
+const node = await figma.getNodeByIdAsync('1234:5678');
+const currentProps = node.type === 'INSTANCE' ? node.componentProperties : {};
+const currentText = node.type === 'TEXT' ? node.characters : null;
+
+return {
+  nodeId: node.id,
+  type: node.type,
+  name: node.name,
+  before: { componentProperties: currentProps, text: currentText },
+};
+
+// Step 2 (separate use_figma call): Apply edits using the values from Step 1
+// Step 3: Call get_screenshot MCP tool to verify — MANDATORY after every significant edit
+```
+
+### Screenshot verification (Path E — edit existing Figma)
+
+After making edits, verify the result visually. This is a **separate MCP tool call**, not Plugin API code.
+
+**After every `use_figma` edit script, immediately call:**
+
+```
+get_screenshot({ nodeId: "1234:5678", fileKey: "abc123" })
+```
+
+Check the screenshot for:
+
+- Text not clipped or overlapping
+- Colors match expected tokens
+- Layout spacing looks correct
+- Component variants show the right state
+
+This catches visual regressions that code inspection alone cannot detect. Always verify after: swapping component variants, changing auto-layout settings, updating text content, or modifying fills/strokes. **Do not skip this step.**
diff --git a/skills/guidelines/components/buttons.md b/skills/guidelines/components/buttons.md
index 16b2884c59..53bcd3d7c7 100644
--- a/skills/guidelines/components/buttons.md
+++ b/skills/guidelines/components/buttons.md
@@ -2,15 +2,15 @@
 
 ## Button
 
-Four variants with clear hierarchy:
+Five variants with clear hierarchy:
 
-| Variant | Color | Use | Limit |
-|---|---|---|---|
-| `primary` | Blue | The single most important action | **One per screen section** |
-| `secondary` | Gray outline | Supporting actions | Default choice |
-| `positive` | Green | Constructive: create, publish, add | |
-| `negative` | Red | Destructive: delete, remove, archive | |
-| `transparent` | None | Lowest priority; light backgrounds only | |
+| Variant       | Token             | Use                                     | Limit                      |
+| ------------- | ----------------- | --------------------------------------- | -------------------------- |
+| `primary`     | `blue600`         | The single most important action        | **One per screen section** |
+| `secondary`   | `gray300` outline | Supporting actions                      | Default choice             |
+| `positive`    | `green600`        | Constructive actions                    |                            |
+| `negative`    | `red600`          | Destructive actions                     |                            |
+| `transparent` | None              | Lowest priority; light backgrounds only |                            |
 
 **Sizes:** `small` (toolbars), `medium` (default), `large` (rare, hero CTAs only)
 
@@ -18,39 +18,47 @@ Four variants with clear hierarchy:
 <Button variant="primary" startIcon={<PlusIcon />}>Add field</Button>
 <Button variant="secondary">Export</Button>
 <Button variant="positive">Publish</Button>
-<Button variant="negative">Delete entry</Button>
+<Button variant="negative" as="a" href="/settings/danger">Delete entry</Button>
 ```
 
-| Prop | Type | Notes |
-|---|---|---|
-| `variant` | `'primary'` `'secondary'` `'positive'` `'negative'` `'transparent'` | |
-| `size` | `'small'` `'medium'` `'large'` | |
-| `startIcon` / `endIcon` | ReactNode | Icon element |
-| `isDisabled` | boolean | |
-| `isLoading` | boolean | Shows spinner — never disable + add spinner manually |
-| `isFullWidth` | boolean | |
-| `as` | ElementType | Use `as="a"` with `href` for navigation buttons |
+| Prop                    | Type                                                                | Notes                                                            |
+| ----------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `variant`               | `'primary'` `'secondary'` `'positive'` `'negative'` `'transparent'` |                                                                  |
+| `size`                  | `'small'` `'medium'` `'large'`                                      |                                                                  |
+| `startIcon` / `endIcon` | ReactNode                                                           | Icon element                                                     |
+| `isDisabled`            | boolean                                                             |                                                                  |
+| `isLoading`             | boolean                                                             | Shows spinner — never disable + add spinner manually             |
+| `isFullWidth`           | boolean                                                             |                                                                  |
+| `isActive`              | boolean                                                             | Active/pressed state (e.g. toggle, current nav item)             |
+| `as`                    | ElementType                                                         | Render as `'a'` for navigation, `'button'` (default) for actions |
+
+Button can render as an `<a>` tag via `as="a"` with `href` — this is the correct way to make a button that navigates to a route.
 
 **Writing rules:**
-- Always start with a verb: "Add field", "Delete entry", "Publish"
+
+- Always start with a verb
 - Max 3 words
 - Sentence case
-- Cancel for destructive actions: **"Never mind"** — not "Cancel"
+- Cancel label for destructive confirmations: **"Never mind"** — not "Cancel"
 
 ## IconButton
 
 Icon-only button with built-in tooltip from `aria-label`.
 
 ```tsx
-<IconButton icon={<MoreHorizontalIcon />} variant="secondary" aria-label="More actions" />
+<IconButton
+  icon={<DotsThreeIcon />}
+  variant="secondary"
+  aria-label="More actions"
+/>
 ```
 
-| Prop | Type | Notes |
-|---|---|---|
-| `icon` | ReactNode | Required |
-| `variant` | Same as Button | |
-| `aria-label` | string | Required — doubles as tooltip |
-| `size` | Same as Button | |
+| Prop         | Type           | Notes                         |
+| ------------ | -------------- | ----------------------------- |
+| `icon`       | ReactNode      | Required                      |
+| `variant`    | Same as Button |                               |
+| `aria-label` | string         | Required — doubles as tooltip |
+| `size`       | Same as Button |                               |
 
 Do not use IconButton for navigation.
 
@@ -63,12 +71,12 @@ For navigation and low-priority actions. Never use Button for navigation.
 <TextLink as="button" onClick={handleClear}>Clear filters</TextLink>
 ```
 
-| Prop | Type | Notes |
-|---|---|---|
-| `as` | `'a'` (default) or `'button'` | `a` = navigation, `button` = action |
-| `variant` | `'primary'` `'positive'` `'negative'` `'secondary'` `'muted'` `'white'` `'premium'` | |
-| `icon` | ReactNode | |
-| `alignIcon` | `'start'` `'end'` | |
+| Prop        | Type                                                                                | Notes                               |
+| ----------- | ----------------------------------------------------------------------------------- | ----------------------------------- |
+| `as`        | `'a'` (default) or `'button'`                                                       | `a` = navigation, `button` = action |
+| `variant`   | `'primary'` `'positive'` `'negative'` `'secondary'` `'muted'` `'white'` `'premium'` |                                     |
+| `icon`      | ReactNode                                                                           |                                     |
+| `alignIcon` | `'start'` `'end'`                                                                   |                                     |
 
 Use `rel="noreferrer noopener"` with `target="_blank"`.
 
@@ -80,8 +88,8 @@ Place at the end of content the user wants to copy.
 <CopyButton value="abc123" tooltipText="Copy ID" />
 ```
 
-| Prop | Type | Notes |
-|---|---|---|
-| `value` | string | Required — the text to copy |
-| `tooltipText` | string | Default: "Copy to clipboard" |
-| `tooltipCopiedText` | string | Default: "Copied!" |
+| Prop                | Type   | Notes                        |
+| ------------------- | ------ | ---------------------------- |
+| `value`             | string | Required — the text to copy  |
+| `tooltipText`       | string | Default: "Copy to clipboard" |
+| `tooltipCopiedText` | string | Default: "Copied!"           |
diff --git a/skills/guidelines/components/data-display.md b/skills/guidelines/components/data-display.md
index 10d2c4fa41..f58248fc3d 100644
--- a/skills/guidelines/components/data-display.md
+++ b/skills/guidelines/components/data-display.md
@@ -14,11 +14,18 @@
   <Table.Body>
     <Table.Row>
       <Table.Cell>Blog Post</Table.Cell>
-      <Table.Cell><EntityStatusBadge entityStatus="published" /></Table.Cell>
+      <Table.Cell>
+        <EntityStatusBadge entityStatus="published" />
+      </Table.Cell>
       <Table.Cell>
         <Menu>
           <Menu.Trigger>
-            <IconButton icon={<MoreHorizontalIcon />} aria-label="Actions" variant="transparent" size="small" />
+            <IconButton
+              icon={<DotsThreeIcon />}
+              aria-label="Actions"
+              variant="transparent"
+              size="small"
+            />
           </Menu.Trigger>
           <Menu.List>
             <Menu.Item>Edit</Menu.Item>
@@ -31,32 +38,44 @@
 </Table>
 ```
 
-| Prop | Component | Notes |
-|---|---|---|
-| `isSticky` | `Table.Head` | Sticky header |
-| `isSelected` | `Table.Row` | Highlight selected rows |
-| `isSortable` / `sortDirection` | `Table.Cell` | Sortable column header |
-| `isTruncated` | `Table.Cell` | Truncate long text |
-| `width` | `Table.Cell` | Fixed column width |
+| Prop                           | Component    | Notes                                                                                          |
+| ------------------------------ | ------------ | ---------------------------------------------------------------------------------------------- |
+| `layout`                       | `Table`      | `'inline'` (default) or `'embedded'` — embedded removes outer borders for nesting inside cards |
+| `isSticky`                     | `Table.Head` | Makes the header stick to the top of the scroll container                                      |
+| `isSelected`                   | `Table.Row`  | Highlight selected rows                                                                        |
+| `isSortable` / `sortDirection` | `Table.Cell` | Sortable column header                                                                         |
+| `isTruncated`                  | `Table.Cell` | Truncate long text                                                                             |
+| `width`                        | `Table.Cell` | Fixed column width                                                                             |
 
-**Loading state:** `Skeleton.Row` inside `Table.Body` with `rowCount` and `columnCount`.
+**Loading state:** Use `Skeleton.Row` inside a `Table.Body` for table loading states. Props: `rowCount` (default 1), `columnCount` (default 5).
 
 ## Card
 
 ```tsx
-<Card onClick={handleClick} padding="default">
+<Card padding="default">
   <Heading>API Keys</Heading>
   <Paragraph>Manage your API keys</Paragraph>
-</Card>
+</Card>;
+
+{
+  /* Interactive card — adds role="button" and focus/hover states automatically */
+}
+<Card onClick={handleClick} padding="default">
+  <Heading>Configure</Heading>
+</Card>;
 ```
 
-| Prop | Notes |
-|---|---|
-| `onClick` | Makes card interactive |
-| `isSelected` | Selection state |
-| `padding` | `'none'` `'default'` `'large'` |
-| `withDragHandle` | Show drag handle |
-| `ariaLabel` | Required when interactive but no visible title |
+| Prop             | Notes                                                                          |
+| ---------------- | ------------------------------------------------------------------------------ |
+| `padding`        | `'none'` `'default'` `'large'`                                                 |
+| `onClick`        | Makes card interactive — automatically adds `role="button"` and `tabIndex={0}` |
+| `href`           | Makes card a link — renders as `<a>`                                           |
+| `isSelected`     | Selection state                                                                |
+| `isLoading`      | Shows skeleton overlay                                                         |
+| `badge`          | ReactNode shown in card header                                                 |
+| `icon`           | ReactNode shown in card header                                                 |
+| `withDragHandle` | Show drag handle                                                               |
+| `ariaLabel`      | Required when interactive but no visible title                                 |
 
 ## EntityList
 
@@ -81,7 +100,7 @@ Status values: `published`, `draft`, `changed`, `archived`.
 Secondary content not needed by default.
 
 ```tsx
-<Accordion>
+<Accordion align="end">
   <Accordion.Item title="Advanced settings">
     <Stack flexDirection="column" spacing="spacingM">
       <FormControl>...</FormControl>
@@ -90,23 +109,41 @@ Secondary content not needed by default.
 </Accordion>
 ```
 
+| Prop    | Component   | Notes                                                  |
+| ------- | ----------- | ------------------------------------------------------ |
+| `align` | `Accordion` | `'start'` or `'end'` (default) — positions the chevron |
+
 ## Skeleton
 
 Show during data fetch. Never show empty state until fetch completes.
 
 ```tsx
-<!-- Full area skeleton -->
 <Skeleton.Container>
   <Skeleton.DisplayText />
   <Skeleton.BodyText numberOfLines={3} />
-</Skeleton.Container>
+</Skeleton.Container>;
 
-<!-- Table skeleton -->
+{
+  /* Table loading state */
+}
 <Table.Body>
-  <Skeleton.Row rowCount={5} columnCount={3} />
-</Table.Body>
+  <Skeleton.Row rowCount={5} columnCount={4} />
+</Table.Body>;
 ```
 
+**Valid Skeleton sub-components:** `Skeleton.Container`, `Skeleton.DisplayText`, `Skeleton.BodyText`, `Skeleton.Image`, `Skeleton.Row`. There is no `Skeleton.Table` or `Skeleton.Cell`.
+
+| Prop                       | Component                                                     | Notes                                    |
+| -------------------------- | ------------------------------------------------------------- | ---------------------------------------- |
+| `isAnimated`               | `Skeleton.Container`                                          | Whether to animate (default `true`)      |
+| `speed`                    | `Skeleton.Container`                                          | Animation speed in seconds (default `2`) |
+| `svgWidth` / `svgHeight`   | `Skeleton.Container`                                          | Dimensions of the SVG container          |
+| `numberOfLines`            | `Skeleton.BodyText`, `Skeleton.DisplayText`                   | Number of text lines (default `1`)       |
+| `offsetTop` / `offsetLeft` | `Skeleton.BodyText`, `Skeleton.DisplayText`, `Skeleton.Image` | Positioning offsets                      |
+| `width` / `height`         | `Skeleton.Image`                                              | Dimensions (default `70`x`70`)           |
+| `rowCount`                 | `Skeleton.Row`                                                | Number of rows (default `1`)             |
+| `columnCount`              | `Skeleton.Row`                                                | Number of columns (default `5`)          |
+
 ## Pagination
 
 ```tsx
@@ -118,6 +155,18 @@ Show during data fetch. Never show empty state until fetch completes.
 />
 ```
 
+| Prop                  | Type                        | Notes                          |
+| --------------------- | --------------------------- | ------------------------------ |
+| `activePage`          | number                      | Current page (0-indexed)       |
+| `onPageChange`        | `(page: number) => void`    | Page change handler            |
+| `totalItems`          | number                      | Total item count               |
+| `itemsPerPage`        | number                      | Items per page                 |
+| `isLastPage`          | boolean                     | Override last-page detection   |
+| `pageLength`          | number                      | Number of page buttons to show |
+| `showViewPerPage`     | boolean                     | Show items-per-page selector   |
+| `viewPerPageLabel`    | string                      | Label for per-page selector    |
+| `onViewPerPageChange` | `(perPage: number) => void` | Per-page change handler        |
+
 ## List
 
 Simple bullet or numbered list.
@@ -130,6 +179,10 @@ Simple bullet or numbered list.
 <List as="ol">...</List>
 ```
 
+| Prop | Type                       | Notes                     |
+| ---- | -------------------------- | ------------------------- |
+| `as` | `'ul'` (default) or `'ol'` | Unordered or ordered list |
+
 ## ProgressStepper
 
 Multi-step progress indicator.
diff --git a/skills/guidelines/components/feedback.md b/skills/guidelines/components/feedback.md
index a045eaba7e..55bdce8277 100644
--- a/skills/guidelines/components/feedback.md
+++ b/skills/guidelines/components/feedback.md
@@ -12,8 +12,9 @@ Notification.error('Upload failed', { duration: 0, withClose: true }); // persis
 ```
 
 **Rules:**
+
 - Active voice, present tense: "Entry published" not "The entry has been published"
-- Max 1–2 sentences
+- Max 1-2 sentences
 - `duration: 0` for errors that need acknowledgment
 - Use `id` to prevent duplicate toasts
 - Do not use Notification for persistent context — use Note
@@ -30,22 +31,22 @@ Persistent inline context. Stays visible until dismissed or the condition change
 <Note variant="positive">Environment published successfully.</Note>
 ```
 
-| Variant | Icon | Use |
-|---|---|---|
-| `primary` | InfoIcon | General information |
-| `neutral` | InfoIcon | Neutral context |
-| `positive` | CheckCircleIcon | Success, confirmation |
-| `warning` | WarningIcon | Caution, potential issues |
-| `negative` | WarningOctagonIcon | Errors, critical issues |
-| `premium` | DiamondIcon | Paid feature context |
-
-| Prop | Type | Notes |
-|---|---|---|
-| `variant` | see above | Default: `'primary'` |
-| `title` | string | Optional heading |
-| `withCloseButton` | boolean | Adds dismiss button |
-| `onClose` | function | Pair with `withCloseButton` |
-| `icon` | ReactNode | Override default variant icon |
+| Variant    | Icon               | Use                       |
+| ---------- | ------------------ | ------------------------- |
+| `primary`  | InfoIcon           | General information       |
+| `neutral`  | InfoIcon           | Neutral context           |
+| `positive` | CheckCircleIcon    | Success, confirmation     |
+| `warning`  | WarningIcon        | Caution, potential issues |
+| `negative` | WarningOctagonIcon | Errors, critical issues   |
+| `premium`  | DiamondIcon        | Paid feature context      |
+
+| Prop              | Type      | Notes                         |
+| ----------------- | --------- | ----------------------------- |
+| `variant`         | see above | Default: `'primary'`          |
+| `title`           | string    | Optional heading              |
+| `withCloseButton` | boolean   | Adds dismiss button           |
+| `onClose`         | function  | Pair with `withCloseButton`   |
+| `icon`            | ReactNode | Override default variant icon |
 
 Place Note near the relevant content, not generically at the top of the page.
 
@@ -54,20 +55,22 @@ Place Note near the relevant content, not generically at the top of the page.
 Labels and status indicators. Keep to one word.
 
 ```tsx
-<Badge variant="positive">Published</Badge>
-<Badge variant="warning">Draft</Badge>
+<Badge variant="positive">Active</Badge>
+<Badge variant="warning">Pending</Badge>
 <Badge variant="featured">New</Badge>
 ```
 
-| Variant | Use |
-|---|---|
-| `primary` | Default |
-| `primary-filled` | Emphasized default |
-| `positive` | Published, active |
-| `negative` | Deleted, error |
-| `warning` | Draft, pending |
-| `secondary` | Muted status |
-| `featured` | Premium, new |
+| Variant          | Use                       |
+| ---------------- | ------------------------- |
+| `primary`        | Default                   |
+| `primary-filled` | Emphasized default        |
+| `positive`       | Active, enabled           |
+| `negative`       | Error, removed            |
+| `warning`        | Pending, attention needed |
+| `secondary`      | Muted status              |
+| `featured`       | Premium, new              |
+
+Do not use Badge for Contentful entity statuses (published, draft, changed, archived) — use `EntityStatusBadge` instead.
 
 Sizes: `default`, `small`. Use `textTransform="none"` when text is already in correct case.
 
diff --git a/skills/guidelines/components/forms.md b/skills/guidelines/components/forms.md
index 1e66227af6..653913b71e 100644
--- a/skills/guidelines/components/forms.md
+++ b/skills/guidelines/components/forms.md
@@ -20,17 +20,18 @@ The wrapper for all form fields. Propagates state to children automatically.
 </FormControl>
 ```
 
-**Structure order:** Label → Input → HelpText → ValidationMessage
+**Structure order:** Label -> Input -> HelpText -> ValidationMessage
 
-| Prop | Type | Notes |
-|---|---|---|
-| `isRequired` | boolean | Shows asterisk on label |
-| `isInvalid` | boolean | Shows validation message, red border on input |
-| `isDisabled` | boolean | Disables the input |
-| `isReadOnly` | boolean | |
-| `as` | `'div'` `'fieldset'` | Use `fieldset` for checkbox/radio groups |
+| Prop         | Type                 | Notes                                         |
+| ------------ | -------------------- | --------------------------------------------- |
+| `isRequired` | boolean              | Shows asterisk on label                       |
+| `isInvalid`  | boolean              | Shows validation message, red border on input |
+| `isDisabled` | boolean              | Disables the input                            |
+| `isReadOnly` | boolean              |                                               |
+| `as`         | `'div'` `'fieldset'` | Use `fieldset` for checkbox/radio groups      |
 
 **Sub-components:**
+
 - `FormControl.Label` — required for accessibility. Use `as="legend"` inside fieldsets
 - `FormControl.HelpText` — always-visible guidance
 - `FormControl.ValidationMessage` — error text, appears when `isInvalid`
@@ -44,16 +45,16 @@ Short free text.
 
 ```tsx
 <TextInput value={val} onChange={e => setVal(e.target.value)} placeholder="e.g. Blog Post" />
-<TextInput type="search" icon={<SearchIcon />} />
+<TextInput type="search" icon={<MagnifyingGlassIcon />} />
 ```
 
-| Prop | Type |
-|---|---|
-| `value` / `onChange` | standard |
-| `placeholder` | string |
-| `size` | `'small'` `'medium'` |
-| `icon` | ReactNode |
-| `type` | `'text'` `'email'` `'number'` `'password'` `'search'` `'url'` |
+| Prop                 | Type                                                          |
+| -------------------- | ------------------------------------------------------------- |
+| `value` / `onChange` | standard                                                      |
+| `placeholder`        | string                                                        |
+| `size`               | `'small'` `'medium'`                                          |
+| `icon`               | ReactNode                                                     |
+| `type`               | `'text'` `'email'` `'number'` `'password'` `'search'` `'url'` |
 
 Use `TextInput.Group` to pair an input with an adjacent action button.
 
@@ -62,15 +63,15 @@ Use `TextInput.Group` to pair an input with an adjacent action button.
 Long-form text. Always inside FormControl.
 
 ```tsx
-<Textarea value={desc} onChange={e => setDesc(e.target.value)} rows={4} />
+<Textarea value={desc} onChange={(e) => setDesc(e.target.value)} rows={4} />
 ```
 
 ## Select
 
-For 2–8 options. Never use Select for triggering actions (use Menu).
+For 2-8 options. Never use Select for triggering actions (use Menu).
 
 ```tsx
-<Select value={type} onChange={e => setType(e.target.value)}>
+<Select value={type} onChange={(e) => setType(e.target.value)}>
   <Select.Option value="text">Text</Select.Option>
   <Select.Option value="number">Number</Select.Option>
 </Select>
@@ -83,9 +84,9 @@ For lists >8 items or when search is needed. Manage filtering externally.
 ```tsx
 <Autocomplete
   items={filteredItems}
-  onSelectItem={item => setSelected(item)}
-  onInputValueChange={val => setFilter(val)}
-  itemToString={item => item?.name ?? ''}
+  onSelectItem={(item) => setSelected(item)}
+  onInputValueChange={(val) => setFilter(val)}
+  itemToString={(item) => item?.name ?? ''}
 />
 ```
 
@@ -95,7 +96,7 @@ Multiple selection from a list.
 
 ```tsx
 <Multiselect currentSelection={selected} placeholder="Select tags">
-  {tags.map(tag => (
+  {tags.map((tag) => (
     <Multiselect.Option
       key={tag.id}
       itemId={tag.id}
@@ -125,7 +126,7 @@ Use `Checkbox.Group` for multiple selections. `isIndeterminate` for partial sele
 Mutually exclusive single selection.
 
 ```tsx
-<Radio.Group value={type} onChange={e => setType(e.target.value)}>
+<Radio.Group value={type} onChange={(e) => setType(e.target.value)}>
   <Radio value="short">Short text</Radio>
   <Radio value="long">Long text</Radio>
 </Radio.Group>
@@ -136,7 +137,9 @@ Mutually exclusive single selection.
 Toggle with immediate effect (no save needed).
 
 ```tsx
-<Switch isChecked={enabled} onChange={() => setEnabled(!enabled)}>Dark mode</Switch>
+<Switch isChecked={enabled} onChange={() => setEnabled(!enabled)}>
+  Dark mode
+</Switch>
 ```
 
 Use Switch when the action takes effect immediately. Use Checkbox when a save is required.
@@ -149,8 +152,8 @@ Calendar date input.
 <DatePicker value={date} onChange={setDate} dateFormat="day" />
 ```
 
-| Prop | Type |
-|---|---|
-| `value` / `onChange` | Date |
-| `dateFormat` | `'full'` `'day'` `'time'` |
-| `minDate` / `maxDate` | Date |
+| Prop                  | Type                      |
+| --------------------- | ------------------------- |
+| `value` / `onChange`  | Date                      |
+| `dateFormat`          | `'full'` `'day'` `'time'` |
+| `minDate` / `maxDate` | Date                      |
diff --git a/skills/guidelines/components/layout.md b/skills/guidelines/components/layout.md
index c20bdeffc4..df2a7f50dd 100644
--- a/skills/guidelines/components/layout.md
+++ b/skills/guidelines/components/layout.md
@@ -1,6 +1,6 @@
 # Layout Components
 
-The hierarchy: `Box` (base) → `Flex` (extends Box + flexbox) → `Stack` (wraps Flex, uniform gap) → `Grid` (CSS grid). `Layout` is the page-level shell.
+The hierarchy: `Box` (base) -> `Flex` (extends Box + flexbox) -> `Stack` (wraps Flex, uniform gap) -> `Grid` (CSS grid). `Layout` is the page-level shell.
 
 ## Box
 
@@ -11,12 +11,12 @@ The base primitive. All layout components extend it.
 <Box as="span" display="inline" marginRight="spacingL">text</Box>
 ```
 
-| Prop | Type | Notes |
-|---|---|---|
-| `as` | `React.ElementType` | Render as any HTML element |
-| `display` | CSS display value | |
-| `margin`, `marginTop/Right/Bottom/Left` | Spacing token | e.g. `"spacingM"` |
-| `padding`, `paddingTop/Right/Bottom/Left` | Spacing token | |
+| Prop                                      | Type                | Notes                      |
+| ----------------------------------------- | ------------------- | -------------------------- |
+| `as`                                      | `React.ElementType` | Render as any HTML element |
+| `display`                                 | CSS display value   |                            |
+| `margin`, `marginTop/Right/Bottom/Left`   | Spacing token       | e.g. `"spacingM"`          |
+| `padding`, `paddingTop/Right/Bottom/Left` | Spacing token       |                            |
 
 Spacing token scale: `'none'` `'spacing2Xs'` `'spacingXs'` `'spacingS'` `'spacingM'` `'spacingL'` `'spacingXl'` `'spacing2Xl'` `'spacing3Xl'` `'spacing4Xl'`
 
@@ -36,39 +36,37 @@ Extends Box with `display: flex` and all flexbox props.
 </Flex>
 ```
 
-| Prop | Type | Default |
-|---|---|---|
-| `flexDirection` | `'row'` `'column'` `'row-reverse'` `'column-reverse'` | — |
-| `gap` | Spacing token or CSS string | — |
-| `justifyContent` | CSS value | — |
-| `alignItems` | CSS value | — |
-| `flexWrap` | `'wrap'` `'nowrap'` | — |
-| `fullWidth` / `fullHeight` | boolean | `false` |
-| `isInline` | boolean | `false` → `inline-flex` |
+| Prop                       | Type                                                  | Default                  |
+| -------------------------- | ----------------------------------------------------- | ------------------------ |
+| `flexDirection`            | `'row'` `'column'` `'row-reverse'` `'column-reverse'` | —                        |
+| `gap`                      | Spacing token or CSS string                           | —                        |
+| `justifyContent`           | CSS value                                             | —                        |
+| `alignItems`               | CSS value                                             | —                        |
+| `flexWrap`                 | `'wrap'` `'nowrap'`                                   | —                        |
+| `fullWidth` / `fullHeight` | boolean                                               | `false`                  |
+| `isInline`                 | boolean                                               | `false` -> `inline-flex` |
 
 ## Stack
 
 Shorthand for uniform-gap stacking. Use for toolbars, form field columns, button groups.
 
 ```tsx
-<!-- Horizontal toolbar -->
 <Stack spacing="spacingS">
   <Button variant="secondary">Export</Button>
   <Button variant="primary">Publish</Button>
 </Stack>
 
-<!-- Vertical form fields -->
 <Stack flexDirection="column" spacing="spacingM">
   <FormControl>...</FormControl>
   <FormControl>...</FormControl>
 </Stack>
 ```
 
-| Prop | Type | Default |
-|---|---|---|
-| `flexDirection` | `'row'` `'column'` | `'row'` |
-| `spacing` | Spacing token | `'spacingM'` |
-| `alignItems` | CSS value | `'center'` |
+| Prop            | Type               | Default      |
+| --------------- | ------------------ | ------------ |
+| `flexDirection` | `'row'` `'column'` | `'row'`      |
+| `spacing`       | Spacing token      | `'spacingM'` |
+| `alignItems`    | CSS value          | `'center'`   |
 
 Do not use Stack for reverse layouts — use `Flex` with `row-reverse` or `column-reverse`.
 
@@ -89,12 +87,12 @@ CSS Grid layout.
 </Grid>
 ```
 
-| Prop | Type | Default |
-|---|---|---|
-| `columns` | number or CSS string | `'auto'` |
-| `rows` | number or CSS string | `'auto'` |
-| `columnGap` | Spacing token | `'spacingM'` |
-| `rowGap` | Spacing token | `'none'` |
+| Prop        | Type                 | Default      |
+| ----------- | -------------------- | ------------ |
+| `columns`   | number or CSS string | `'auto'`     |
+| `rows`      | number or CSS string | `'auto'`     |
+| `columnGap` | Spacing token        | `'spacingM'` |
+| `rowGap`    | Spacing token        | `'none'`     |
 
 `Grid.Item` props: `area`, `columnStart/End`, `rowStart/End`, `alignSelf`, `order`.
 
@@ -107,7 +105,10 @@ Replaces the deprecated `Workbench`. Provides the app-page frame.
   variant="wide"
   header={
     <Layout.Header>
-      <Header title="Experiences" actions={<Button variant="primary">Create</Button>} />
+      <Header
+        title="Experiences"
+        actions={<Button variant="primary">Create</Button>}
+      />
     </Layout.Header>
   }
   leftSidebar={
@@ -122,18 +123,52 @@ Replaces the deprecated `Workbench`. Provides the app-page frame.
 </Layout>
 ```
 
-| Prop | Type | Default |
-|---|---|---|
-| `variant` | `'narrow'` `'wide'` `'fullscreen'` | `'wide'` |
-| `header` | ReactNode (wrap in `Layout.Header`) | — |
-| `leftSidebar` | ReactNode (wrap in `Layout.Sidebar`) | — |
-| `rightSidebar` | ReactNode (wrap in `Layout.Sidebar`) | — |
-| `leftSidebarVariant` | `'narrow'` (280px) `'wide'` (340px) | `'narrow'` |
-| `rightSidebarVariant` | `'narrow'` (280px) `'wide'` (340px) | `'wide'` |
-| `offsetTop` | number (px) | `60` |
+| Prop                  | Type                                 | Default    |
+| --------------------- | ------------------------------------ | ---------- |
+| `variant`             | `'narrow'` `'wide'` `'fullscreen'`   | `'wide'`   |
+| `header`              | ReactNode (wrap in `Layout.Header`)  | —          |
+| `leftSidebar`         | ReactNode (wrap in `Layout.Sidebar`) | —          |
+| `rightSidebar`        | ReactNode (wrap in `Layout.Sidebar`) | —          |
+| `leftSidebarVariant`  | `'narrow'` (280px) `'wide'` (340px)  | `'narrow'` |
+| `rightSidebarVariant` | `'narrow'` (280px) `'wide'` (340px)  | `'wide'`   |
+| `offsetTop`           | number (px)                          | `60`       |
 
 **Rules:**
+
 - Always wrap body content in `Layout.Body`
 - Never nest Layout inside Layout or inside Modal
 - Set `dividerLine={true}` on Header when a right sidebar is present
 - `offsetTop={0}` for standalone apps without the Contentful navbar
+
+**Compound sub-components (verified in @contentful/f36-layout source):**
+
+| Sub-component    | Renders as | Purpose                                                              |
+| ---------------- | ---------- | -------------------------------------------------------------------- |
+| `Layout.Header`  | `<header>` | Wraps the `Header` component; pass via the `header` prop             |
+| `Layout.Body`    | `<div>`    | Main content wrapper; handles overflow and scrolling                 |
+| `Layout.Sidebar` | `<aside>`  | Left or right sidebar; pass via `leftSidebar` / `rightSidebar` props |
+
+These are the ONLY valid sub-components. They are real, exported, typed compound components — not fabricated.
+
+```tsx
+import { Layout, Header } from '@contentful/f36-components';
+
+// Correct usage — all three sub-components
+<Layout
+  header={
+    <Layout.Header>
+      <Header title="Page" />
+    </Layout.Header>
+  }
+  leftSidebar={<Layout.Sidebar>nav here</Layout.Sidebar>}
+>
+  <Layout.Body>content here</Layout.Body>
+</Layout>;
+```
+
+**Does NOT exist — never use:**
+
+- ~~`Layout.Content`~~ — use `Layout.Body`
+- ~~`Layout.Footer`~~ — no footer sub-component; place footer content inside `Layout.Body`
+- ~~`Layout.Main`~~ — use `Layout.Body`
+- ~~`Layout.Nav`~~ — use `Layout.Sidebar` with `leftSidebar` prop
diff --git a/skills/guidelines/components/navigation.md b/skills/guidelines/components/navigation.md
index ddfb8e6aa1..964f858ccc 100644
--- a/skills/guidelines/components/navigation.md
+++ b/skills/guidelines/components/navigation.md
@@ -15,18 +15,19 @@ Navigate between sections of related content. Maximum 6 tabs.
 </Tabs>
 ```
 
-| Prop | Notes |
-|---|---|
-| `defaultTab` | Initial active tab ID |
-| `currentTab` / `onTabChange` | Controlled mode |
-| `Tabs.List variant` | `'default'` `'horizontal-divider'` `'vertical-divider'` |
-| `Tabs.Panel forceMount` | Keep mounted (for form state, animation) |
+| Prop                         | Notes                                                   |
+| ---------------------------- | ------------------------------------------------------- |
+| `defaultTab`                 | Initial active tab ID                                   |
+| `currentTab` / `onTabChange` | Controlled mode                                         |
+| `Tabs.List variant`          | `'default'` `'horizontal-divider'` `'vertical-divider'` |
+| `Tabs.Panel forceMount`      | Keep mounted (for form state, animation)                |
 
 Labels must be concise and describe the panel content accurately.
 
 ## Modal
 
 Blocks the interface. Use only when:
+
 - An action needs confirmation before proceeding
 - Information is essential to the current workflow
 
@@ -34,10 +35,14 @@ Blocks the interface. Use only when:
 <Modal isShown={isOpen} onClose={() => setIsOpen(false)}>
   <Modal.Header title="Delete content type" onClose={() => setIsOpen(false)} />
   <Modal.Content>
-    <Paragraph>This content type and all its fields will be permanently deleted.</Paragraph>
+    <Paragraph>
+      This content type and all its fields will be permanently deleted.
+    </Paragraph>
   </Modal.Content>
   <Modal.Controls>
-    <Button variant="secondary" onClick={() => setIsOpen(false)}>Never mind</Button>
+    <Button variant="secondary" onClick={() => setIsOpen(false)}>
+      Never mind
+    </Button>
     <Button variant="negative" isLoading={deleting} onClick={handleDelete}>
       Delete content type
     </Button>
@@ -45,14 +50,15 @@ Blocks the interface. Use only when:
 </Modal>
 ```
 
-| Prop | Notes |
-|---|---|
-| `size` | `'small'` `'medium'` `'large'` `'fullWidth'` `'fullscreen'` |
-| `shouldCloseOnOverlayClick` | `false` for destructive modals |
-| `shouldCloseOnEscapePress` | default `true` |
-| `initialFocusRef` | Focus a specific element on open |
+| Prop                        | Notes                                                       |
+| --------------------------- | ----------------------------------------------------------- |
+| `size`                      | `'small'` `'medium'` `'large'` `'fullWidth'` `'fullscreen'` |
+| `shouldCloseOnOverlayClick` | `false` for destructive modals                              |
+| `shouldCloseOnEscapePress`  | default `true`                                              |
+| `initialFocusRef`           | Focus a specific element on open                            |
 
 **Rules:**
+
 - Title: verb + noun ("Delete content type")
 - Confirm button: verb + noun, matching the title
 - Cancel: "Never mind"
@@ -66,7 +72,11 @@ Action list triggered by a button.
 ```tsx
 <Menu>
   <Menu.Trigger>
-    <IconButton icon={<MoreHorizontalIcon />} aria-label="Actions" variant="secondary" />
+    <IconButton
+      icon={<DotsThreeIcon />}
+      aria-label="Actions"
+      variant="secondary"
+    />
   </Menu.Trigger>
   <Menu.List>
     <Menu.Item onClick={handleEdit}>Edit</Menu.Item>
@@ -91,15 +101,16 @@ Supplementary, non-critical context on hover/focus.
 </Tooltip>
 ```
 
-| Prop | Notes |
-|---|---|
-| `content` | Short text — one sentence max |
-| `id` | Required for ARIA |
-| `placement` | Positioning |
-| `showDelay` | Default 375ms |
+| Prop        | Notes                               |
+| ----------- | ----------------------------------- |
+| `content`   | Short text — one sentence max       |
+| `id`        | Required for ARIA                   |
+| `placement` | Positioning                         |
+| `showDelay` | Default 375ms                       |
 | `usePortal` | Use with `overflow: hidden` parents |
 
 **Rules:**
+
 - No buttons, links, or forms inside Tooltip content
 - Content must be non-critical — if the user needs this info, put it in the UI
 - Always include a unique `id`
@@ -125,8 +136,12 @@ Vertical sidebar navigation.
 
 ```tsx
 <NavList aria-label="Main navigation">
-  <NavList.Item as="a" href="/experiences" isActive>Experiences</NavList.Item>
-  <NavList.Item as="a" href="/content">Content</NavList.Item>
+  <NavList.Item as="a" href="/experiences" isActive>
+    Experiences
+  </NavList.Item>
+  <NavList.Item as="a" href="/content">
+    Content
+  </NavList.Item>
 </NavList>
 ```
 
diff --git a/skills/guidelines/components/overview.md b/skills/guidelines/components/overview.md
index e3781d4398..f768bca15f 100644
--- a/skills/guidelines/components/overview.md
+++ b/skills/guidelines/components/overview.md
@@ -3,58 +3,68 @@
 All components import from `@contentful/f36-components` unless noted otherwise.
 
 ```tsx
-import { Button, Stack, FormControl, TextInput } from '@contentful/f36-components';
+import {
+  Button,
+  Stack,
+  FormControl,
+  TextInput,
+} from '@contentful/f36-components';
 ```
 
 ## Choosing a component
 
 **I need to arrange items on screen:**
-- Toolbar / inline group with uniform gap → `Stack`
-- Complex alignment (space-between, mixed sizes) → `Flex`
-- Two-dimensional grid → `Grid`
-- Full page shell with header/sidebar → `Layout`
-- Just padding/margin → `Box`
+
+- Toolbar / inline group with uniform gap -> `Stack`
+- Complex alignment (space-between, mixed sizes) -> `Flex`
+- Two-dimensional grid -> `Grid`
+- Full page shell with header/sidebar -> `Layout`
+- Just padding/margin -> `Box`
 
 **I need user input:**
-- Short free text → `TextInput`
-- Long free text → `Textarea`
-- Pick one from ≤8 options → `Select`
-- Pick one from >8 options → `Autocomplete`
-- Toggle a setting → `Switch` (immediate effect) or `Checkbox` (requires save)
-- Pick one from a mutually exclusive group → `Radio.Group`
-- Pick multiple from a list → `Multiselect`
-- Pick a date → `DatePicker`
+
+- Short free text -> `TextInput`
+- Long free text -> `Textarea`
+- Pick one from <=8 options -> `Select`
+- Pick one from >8 options -> `Autocomplete`
+- Toggle a setting -> `Switch` (immediate effect) or `Checkbox` (requires save)
+- Pick one from a mutually exclusive group -> `Radio.Group`
+- Pick multiple from a list -> `Multiselect`
+- Pick a date -> `DatePicker`
 
 **I need to trigger an action:**
-- Primary page action → `Button variant="primary"` (one per section max)
-- Supporting action → `Button variant="secondary"`
-- Constructive action (create, publish) → `Button variant="positive"`
-- Destructive action → `Button variant="negative"`
-- Icon-only action → `IconButton`
-- Navigation → `TextLink` (never `Button`)
-- Action list from a trigger → `Menu`
+
+- Primary page action -> `Button variant="primary"` (one per section max)
+- Supporting action -> `Button variant="secondary"`
+- Constructive action (create, publish) -> `Button variant="positive"`
+- Destructive action -> `Button variant="negative"`
+- Icon-only action -> `IconButton`
+- Navigation -> `TextLink` (never `Button`)
+- Action list from a trigger -> `Menu`
 
 **I need to show feedback:**
-- Temporary toast after action → `Notification`
-- Persistent inline context → `Note`
-- Status label → `Badge` (or `EntityStatusBadge` for Contentful entities)
-- Loading → `Skeleton` (data fetch) or `Spinner` (full area)
+
+- Temporary toast after action -> `Notification`
+- Persistent inline context -> `Note`
+- Status label -> `Badge` (or `EntityStatusBadge` for Contentful entities)
+- Loading -> `Skeleton` (data fetch) or `Spinner` (full area)
 
 **I need navigation/overlays:**
-- Sidebar navigation → `NavList`
-- Content sections → `Tabs` (max 6)
-- Workflow-blocking confirmation → `Modal`
-- Supplementary hover context → `Tooltip`
+
+- Sidebar navigation -> `NavList`
+- Content sections -> `Tabs` (max 6)
+- Workflow-blocking confirmation -> `Modal`
+- Supplementary hover context -> `Tooltip`
 
 ## Component files
 
-| File | Components covered |
-|---|---|
-| `layout.md` | Box, Flex, Stack, Grid, Layout |
-| `buttons.md` | Button, IconButton, TextLink, CopyButton |
-| `forms.md` | FormControl, TextInput, Textarea, Select, Autocomplete, Multiselect, Checkbox, Radio, Switch, DatePicker |
-| `feedback.md` | Notification, Note, Badge, EntityStatusBadge, Spinner |
-| `navigation.md` | Tabs, Modal, Menu, Tooltip, Popover, NavList |
-| `data-display.md` | Table, Card, EntityList, Accordion, Collapse, Skeleton, Pagination, List, ProgressStepper |
-| `content-media.md` | Asset, Avatar, Image, DateTime, UsageCard |
-| `utility.md` | DragHandle, Pill, Typography components (DisplayText, Heading, Subheading, SectionHeading, Paragraph, Text), Header |
+| File               | Components covered                                                                                                  |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------- |
+| `layout.md`        | Box, Flex, Stack, Grid, Layout                                                                                      |
+| `buttons.md`       | Button, IconButton, TextLink, CopyButton                                                                            |
+| `forms.md`         | FormControl, TextInput, Textarea, Select, Autocomplete, Multiselect, Checkbox, Radio, Switch, DatePicker            |
+| `feedback.md`      | Notification, Note, Badge, EntityStatusBadge, Spinner                                                               |
+| `navigation.md`    | Tabs, Modal, Menu, Tooltip, Popover, NavList                                                                        |
+| `data-display.md`  | Table, Card, EntityList, Accordion, Collapse, Skeleton, Pagination, List, ProgressStepper                           |
+| `content-media.md` | Asset, Avatar, Image, DateTime, UsageCard                                                                           |
+| `utility.md`       | DragHandle, Pill, Typography components (DisplayText, Heading, Subheading, SectionHeading, Paragraph, Text), Header |
diff --git a/skills/guidelines/components/utility.md b/skills/guidelines/components/utility.md
index 85d3a52524..b76563494b 100644
--- a/skills/guidelines/components/utility.md
+++ b/skills/guidelines/components/utility.md
@@ -3,30 +3,42 @@
 ## Typography
 
 ```tsx
-import { DisplayText, Heading, Subheading, SectionHeading, Paragraph, Text } from '@contentful/f36-components';
+import {
+  DisplayText,
+  Heading,
+  Subheading,
+  SectionHeading,
+  Paragraph,
+  Text,
+} from '@contentful/f36-components';
 ```
 
-| Component | Size | Use |
-|---|---|---|
-| `DisplayText` | 2xl–4xl | Hero/splash headings only |
-| `Heading` | xl | Page section titles |
-| `Subheading` | l | Sub-section titles |
-| `SectionHeading` | s, 600 weight | Nav group labels, table column headers |
-| `Paragraph` | m | Body copy |
-| `Text` | any | Inline styled text with token overrides |
+| Component        | Size          | Use                                     |
+| ---------------- | ------------- | --------------------------------------- |
+| `DisplayText`    | 2xl-4xl       | Hero/splash headings only               |
+| `Heading`        | xl            | Page section titles                     |
+| `Subheading`     | l             | Sub-section titles                      |
+| `SectionHeading` | s, 600 weight | Nav group labels, table column headers  |
+| `Paragraph`      | m             | Body copy                               |
+| `Text`           | any           | Inline styled text with token overrides |
 
-Use the `as` prop to decouple HTML element from visual size. Never skip heading levels (h1 → h3).
+Use the `as` prop to decouple HTML element from visual size. Never skip heading levels (h1 -> h3).
 
 ## Header
 
 Every page must have one. Two variants:
 
 **Title variant** — top-level pages:
+
 ```tsx
-<Header title="Experiences" actions={<Button variant="primary">Create</Button>} />
+<Header
+  title="Experiences"
+  actions={<Button variant="primary">Create</Button>}
+/>
 ```
 
 **Breadcrumb variant** — subpages:
+
 ```tsx
 <Header
   title="Blog Post"
@@ -36,14 +48,14 @@ Every page must have one. Two variants:
 />
 ```
 
-| Prop | Notes |
-|---|---|
-| `title` | Page title text |
-| `actions` | Right-aligned action buttons |
-| `breadcrumbs` | Parent path for subpages |
-| `withBackButton` | Show back arrow |
-| `filters` | Filter controls below title |
-| `dividerLine` | Set `true` when right sidebar is present |
+| Prop             | Notes                                    |
+| ---------------- | ---------------------------------------- |
+| `title`          | Page title text                          |
+| `actions`        | Right-aligned action buttons             |
+| `breadcrumbs`    | Parent path for subpages                 |
+| `withBackButton` | Show back arrow                          |
+| `filters`        | Filter controls below title              |
+| `dividerLine`    | Set `true` when right sidebar is present |
 
 Rules: actions slot order is secondary buttons first, primary last.
 
@@ -71,17 +83,17 @@ Variants: `idle`, `active`, `deleted`.
 ## Icons
 
 ```tsx
-import { PlusIcon, DeleteIcon, SearchIcon, MoreHorizontalIcon } from '@contentful/f36-icons';
+import { PlusIcon, TrashSimpleIcon, MagnifyingGlassIcon, DotsThreeIcon } from '@contentful/f36-icons';
 
 <Button startIcon={<PlusIcon />}>Add field</Button>
 <PlusIcon size="medium" color={tokens.blue600} />
 ```
 
-| Size | Pixels | Use |
-|---|---|---|
-| `tiny` | 14px | Caption text, metadata |
-| `small` | 16px (default) | Nav items, form fields, buttons |
-| `medium` | 20px | Body text, headings |
+| Size     | Pixels         | Use                             |
+| -------- | -------------- | ------------------------------- |
+| `tiny`   | 14px           | Caption text, metadata          |
+| `small`  | 16px (default) | Nav items, form fields, buttons |
+| `medium` | 20px           | Body text, headings             |
 
 **Regular** = outline (default). **Duotone** = active/toggled state.
 
diff --git a/skills/guidelines/composition/base-shell.md b/skills/guidelines/composition/base-shell.md
index 788d16293c..b93a4ce38c 100644
--- a/skills/guidelines/composition/base-shell.md
+++ b/skills/guidelines/composition/base-shell.md
@@ -20,10 +20,11 @@ Every Contentful screen uses this exact shell. Do not invent alternative chrome.
 
 Height `52px`, background `gray100`. Horizontal padding: `24px` left, `64px` right (the 64px gap is reserved for the agent strip).
 
-**Left side:** Contentful "C" logo → Space/Environment switcher pill
-**Right side:** Search icon → Help icon → User avatar (24px)
+**Left side:** Contentful "C" logo -> Space/Environment switcher pill
+**Right side:** Search icon -> Help icon -> User avatar (24px)
 
 **Environment switcher:**
+
 - Background: `green100`
 - Border: `green400`
 - Text: `green700` — "Space > Production"
@@ -32,33 +33,36 @@ Height `52px`, background `gray100`. Horizontal padding: `24px` left, `64px` rig
 
 ## Sidebar
 
-Width `240px`, white background, `shadowDefault`, top corners rounded to `12px`.
+Width `240px`, white background, `boxShadowDefault`, top corners rounded to `12px`.
 Padding: `pt-12px pb-8px px-4px`. Inner menu: `px-12px`, gap between sections `12px`.
 
 Always implement the sidebar faithfully — replicate all sections, items, icons, and states exactly. Never stub or simplify it.
 
 **Nav item** (32px tall): `px-12px py-6px`, `gap-8px`, `border-radius: 4px`
+
 - Icon (16px, duotone for active) + label (body, `gray900`) + optional caret
 - Active: `blue100` background
 - Default: transparent
 - Hover: `gray100` background
 
 **Sections** (separated by `gray200` bottom border):
+
 1. **Setup** — Design System, Content Model
 2. **Creation** — Experiences, Content
 3. **Optimization** — Optimizations, Analytics
 4. **Platform Configuration** — Collections, AI & Automations, Taxonomy, Apps
-5. *(no title)* — Settings
+5. _(no title)_ — Settings
 
 Section title: `12px` size, `600` weight, `gray700`, `28px` tall, `pl-12px`.
 Collapse button: transparent `IconButton` with `CaretLeft` icon, bottom-right of sidebar.
 
 ## Content area
 
-Fills remaining width. White background, `shadowDefault`, top corners rounded to `12px`.
+Fills remaining width. White background, `boxShadowDefault`, top corners rounded to `12px`.
 Padding: `pt-12px px-24px`.
 
 **Top:** `Header` component — always present, never omit.
+
 - Use `Title` variant for top-level pages
 - Use `Breadcrumb` variant for subpages
 - Set `dividerLine={true}` when content area has a right sidebar
diff --git a/skills/guidelines/composition/screen-patterns.md b/skills/guidelines/composition/screen-patterns.md
index 09303e122f..320b04e605 100644
--- a/skills/guidelines/composition/screen-patterns.md
+++ b/skills/guidelines/composition/screen-patterns.md
@@ -22,15 +22,24 @@ Content
 ```
 
 **Rules:**
+
 - Primary action ("Create experience") is top-right in Header
-- Row actions via Menu with IconButton trigger (MoreHorizontalIcon) — not inline buttons
+- Row actions via Menu with IconButton trigger (`DotsThreeIcon`) — not inline buttons
 - Status column uses `EntityStatusBadge`
 - Bulk selection: checkbox column left, bulk action bar above table
-- Loading: `Skeleton.Row` inside table body
+- Loading: `Skeleton.Row` inside `Table.Body` (props: `rowCount`, `columnCount`)
 
 **Empty state (no items):** "No [items] yet" + one sentence about purpose + primary create button
 **Empty state (no search results):** `No results for "[query]"` + "Try a different search term or clear filters." + TextLink "Clear filters"
 
+**Common list page mistakes — avoid these:**
+
+- Row action trigger: use `<IconButton icon={<DotsThreeIcon />} />` — never `MoreHorizontalIcon`, `MoreVerticalIcon`, or `EllipsisIcon`
+- Search input: must be inside a `FormControl` with a `Label` (use `visually-hidden` Label if no visible label desired)
+- Loading skeleton: use `Skeleton.Row` for tables — it renders the right number of rows and columns automatically
+- Sidebar nav icons: use only icons from `@contentful/f36-icons` — never `HomeIcon`, `SettingsIcon` (use `HouseIcon`, `GearSixIcon`, etc.)
+- Table column widths: use token-based spacing or percentage values, not arbitrary pixel widths
+
 ---
 
 ## Detail / Edit Page
@@ -49,6 +58,7 @@ Content (two-column when sidebar present)
 ```
 
 **Rules:**
+
 - `dividerLine={true}` on Header when right sidebar present
 - Publish button: `positive` variant — "Publish"
 - Save draft: `secondary` — "Save"
@@ -74,9 +84,10 @@ Content
 ```
 
 **Rules:**
+
 - Group under `Heading` / `SectionHeading` with `gray200` divider
 - Danger zone always at very bottom, visually separated
-- Destructive actions: `negative` Button → confirmation Modal
+- Destructive actions: `negative` Button -> confirmation Modal
 - Inline save: `Notification.success` — don't navigate away
 
 ---
@@ -94,11 +105,13 @@ Centered container (vertical + horizontal)
 ```
 
 **Heading formulas:**
+
 - First-time: "No [content types] yet"
 - No results: `No results for "[query]"`
 - Permission: "You don't have access to [section]"
 
 **Body formulas:**
+
 - First-time: "[Section] lets you [purpose]. Start by [action]."
 - No results: "Try a different search term or adjust filters."
 - Error: "Something went wrong while loading [items]."
@@ -118,6 +131,7 @@ Centered container
 ```
 
 **Rules:**
+
 - "Couldn't load" not "Error 500" — humanize
 - Always offer a recovery action
 - Log technical details to console
@@ -137,6 +151,7 @@ Modal size="small"
 ```
 
 **Rules:**
+
 - Title and confirm button always match: same verb + noun
 - Confirm: `negative` variant
 - Cancel: "Never mind" — never "Cancel", "No", "Go back"
@@ -158,6 +173,7 @@ Layout variant="narrow" or Modal size="large"/"fullscreen"
 ```
 
 **Rules:**
+
 - "Back" on left, "Continue" on right
 - Final step: `positive` variant — "Create [thing]" or "Finish setup"
 - Show progress indicator — never leave users guessing
@@ -180,10 +196,11 @@ Content
 ```
 
 **Rules:**
+
 - Metric cards: equal width, `padding="default"`
 - Max 4 cards per row
-- Recent activity: 5–10 items, link to full list
-- Loading: `Skeleton.Container` per card
+- Recent activity: 5-10 items, link to full list
+- Loading: `Skeleton.Container` with `Skeleton.BodyText` per card
 - Empty state per section independently
 
 ---
@@ -203,8 +220,23 @@ Layout variant="narrow"
 ```
 
 **Rules:**
+
 - Use `Layout variant="narrow"` — never full width
 - Group related fields under Heading
 - `isRequired` on FormControl for required fields
 - Validate inline, on blur or submit
 - On success: `Notification.success` + navigate to result
+
+---
+
+## Navigation Hierarchy
+
+| Level                          | Pattern                              |
+| ------------------------------ | ------------------------------------ |
+| Top-level sections             | Left sidebar sections                |
+| Sub-sections within a section  | Tabs in the content area             |
+| Drill-down to a single item    | Header with Breadcrumb + back button |
+| Related views on a single item | Tabs in the detail page content area |
+
+**Never use modals as navigation.** A modal should complete a task, not replace a page.
+**Never use Tabs at the sidebar level** — sidebar items navigate between sections, not tabs.
diff --git a/skills/guidelines/foundations/icons.md b/skills/guidelines/foundations/icons.md
index c24559c208..54ff453e35 100644
--- a/skills/guidelines/foundations/icons.md
+++ b/skills/guidelines/foundations/icons.md
@@ -3,7 +3,11 @@
 Forma 36 uses the **Phosphor** icon library exclusively.
 
 ```tsx
-import { PlusIcon, SearchIcon, DeleteIcon } from '@contentful/f36-icons';
+import {
+  PlusIcon,
+  MagnifyingGlassIcon,
+  TrashSimpleIcon,
+} from '@contentful/f36-icons';
 ```
 
 ## Styles
@@ -17,31 +21,86 @@ Never use filled solid single-color icons. Never use icons from Material Icons,
 
 Match icon size to the text it accompanies:
 
-| Context | Size | Pixels |
-|---|---|---|
-| Caption text, metadata | `tiny` | 14px |
-| Nav items, form fields, buttons | `small` (default) | 16px |
-| Body text, headings | `medium` | 20px |
+| Context                         | Size              | Pixels |
+| ------------------------------- | ----------------- | ------ |
+| Caption text, metadata          | `tiny`            | 14px   |
+| Nav items, form fields, buttons | `small` (default) | 16px   |
+| Body text, headings             | `medium`          | 20px   |
 
 ## Color
 
 Match icon color to its semantic role:
 
-| Role | Token |
-|---|---|
-| Default / neutral | `gray900` |
-| Muted / decorative | `gray600` |
-| Active / primary action | `blue600` |
-| On dark backgrounds | `colorWhite` |
-| Success | `green600` |
-| Destructive / error | `red600` |
-| Warning | `orange400` |
-| Premium / new feature | `purple600` (sparingly) |
+| Role                    | Token                   |
+| ----------------------- | ----------------------- |
+| Default / neutral       | `gray900`               |
+| Muted / decorative      | `gray600`               |
+| Active / primary action | `blue600`               |
+| On dark backgrounds     | `colorWhite`            |
+| Success                 | `green600`              |
+| Destructive / error     | `red600`                |
+| Warning                 | `orange400`             |
+| Premium / new feature   | `purple600` (sparingly) |
 
 ## Labels
 
 Most icons need a visible text label. Icons may appear without labels only when:
+
 - Universally understood (magnifying glass for search, question mark for help, gear for settings)
 - In a consistent, expected position
 
 When in doubt, add a label or tooltip. Icon-only buttons always need `aria-label`.
+
+## Valid icon names — closed set
+
+These are the most commonly used icons in `@contentful/f36-icons`. **Only use names from this list.** If you need an icon not listed here, check the [Phosphor icon set](https://phosphoricons.com/) and use the PascalCase + `Icon` suffix convention — but NEVER invent a name.
+
+### Actions & Navigation
+
+`PlusIcon` `MinusIcon` `MinusCircleIcon` `XIcon` `XSquareIcon` `MagnifyingGlassIcon` `FunnelSimpleIcon` `SortAscendingIcon` `SortDescendingIcon` `ArrowUpIcon` `ArrowDownIcon` `ArrowLeftIcon` `ArrowRightIcon` `ArrowsOutIcon` `ArrowSquareOutIcon` `ArrowClockwiseIcon` `ArrowCounterClockwiseIcon` `CaretDownIcon` `CaretUpIcon` `CaretLeftIcon` `CaretRightIcon` `CaretUpDownIcon` `LinkSimpleIcon` `LinkBreakIcon` `DownloadSimpleIcon` `SignInIcon` `SignOutIcon` `SwapIcon` `RepeatIcon`
+
+### Content & Editing
+
+`PencilSimpleIcon` `TrashSimpleIcon` `CopySimpleIcon` `FileIcon` `FileTextIcon` `FileImageIcon` `FileCodeIcon` `FolderSimpleIcon` `FolderOpenIcon` `FolderSimplePlusIcon` `ImageSquareIcon` `ImagesSquareIcon` `TextAlignLeftIcon` `TextAlignCenterIcon` `TextAlignRightIcon` `ListBulletsIcon` `ListNumbersIcon` `ListIcon` `CodeSimpleIcon` `CalendarBlankIcon` `CalendarDotsIcon` `ClockIcon` `TagIcon` `PaintBrushIcon` `PenNibIcon`
+
+### Communication & Status
+
+`ChatIcon` `EnvelopeIcon` `BellIcon` `CheckIcon` `CheckCircleIcon` `WarningIcon` `WarningOctagonIcon` `InfoIcon` `QuestionIcon` `EyeIcon` `EyeClosedIcon` `LockSimpleIcon` `LockSimpleOpenIcon` `KeyIcon` `KeyholeIcon` `FingerprintIcon`
+
+### UI & System
+
+`GearSixIcon` `DotsThreeIcon` `DotsThreeVerticalIcon` `DotsSixVerticalIcon` `GridFourIcon` `ColumnsIcon` `RowsIcon` `StarIcon` `HeartStraightIcon` `BookmarkSimpleIcon` `GlobeIcon` `GlobeXIcon` `UserIcon` `UsersIcon` `UsersThreeIcon` `LightningIcon` `RocketIcon` `RocketLaunchIcon` `LightbulbIcon` `FlaskIcon` `DiamondIcon` `CubeIcon` `TreeStructureIcon` `StackIcon` `WrenchIcon` `GaugeIcon`
+
+### Content modeling & Contentful-specific (custom icons)
+
+`EntryIcon` `EnvironmentIcon` `EnvironmentAliasIcon` `ReleaseIcon` `RichTextIcon` `EmbeddedBlockIcon` `EmbeddedLineIcon` `SparkleIcon` `SparkleFilledIcon` `DashboardIcon` `WorkflowsIcon` `InspectorModeIcon` `VariableIcon` `ReplaceIcon` `FallbackIcon`
+
+### WRONG names — never use these
+
+- ~~`MoreHorizontalIcon`~~ → use `DotsThreeIcon`
+- ~~`MoreVerticalIcon`~~ → use `DotsThreeVerticalIcon`
+- ~~`DeleteIcon`~~ → use `TrashSimpleIcon`
+- ~~`EditIcon`~~ → use `PencilSimpleIcon`
+- ~~`SettingsIcon`~~ → use `GearSixIcon`
+- ~~`RefreshIcon`~~ → use `ArrowClockwiseIcon` or `RepeatIcon`
+- ~~`MenuIcon`~~ → use `ListIcon`
+- ~~`AlertIcon`~~ → use `WarningIcon`
+- ~~`SearchIcon`~~ → use `MagnifyingGlassIcon`
+- ~~`TrashIcon`~~ → use `TrashSimpleIcon`
+- ~~`PencilIcon`~~ → use `PencilSimpleIcon`
+- ~~`GearIcon`~~ → use `GearSixIcon`
+- ~~`CopyIcon`~~ → use `CopySimpleIcon`
+- ~~`FilterIcon`~~ → use `FunnelSimpleIcon`
+- ~~`CloseIcon`~~ → use `XIcon`
+- ~~`DownloadIcon`~~ → use `DownloadSimpleIcon`
+- ~~`LinkIcon`~~ → use `LinkSimpleIcon`
+- ~~`LockIcon`~~ → use `LockSimpleIcon`
+- ~~`LockOpenIcon`~~ → use `LockSimpleOpenIcon`
+- ~~`FolderIcon`~~ → use `FolderSimpleIcon`
+- ~~`ImageIcon`~~ → use `ImageSquareIcon`
+- ~~`CalendarIcon`~~ → use `CalendarBlankIcon`
+- ~~`CodeIcon`~~ → use `CodeSimpleIcon`
+- ~~`BookmarkIcon`~~ → use `BookmarkSimpleIcon`
+- ~~`HeartIcon`~~ → use `HeartStraightIcon`
+- ~~`EyeSlashIcon`~~ → use `EyeClosedIcon`
+- ~~`ExternalLinkIcon`~~ → use `ArrowSquareOutIcon`
diff --git a/skills/guidelines/foundations/writing.md b/skills/guidelines/foundations/writing.md
index 6c83e79843..35723b49c3 100644
--- a/skills/guidelines/foundations/writing.md
+++ b/skills/guidelines/foundations/writing.md
@@ -4,12 +4,12 @@ The Contentful interface is clear, direct, respectful, and calm.
 
 ## Voice
 
-| Quality | What it means |
-|---|---|
-| **Clear** | Say exactly what you mean. No jargon, no hedging. |
-| **Direct** | Lead with the action or outcome. Do not bury the point. |
-| **Respectful** | Treat users as capable adults. Do not over-explain. |
-| **Calm** | Even error messages stay composed. The interface never panics. |
+| Quality        | What it means                                                  |
+| -------------- | -------------------------------------------------------------- |
+| **Clear**      | Say exactly what you mean. No jargon, no hedging.              |
+| **Direct**     | Lead with the action or outcome. Do not bury the point.        |
+| **Respectful** | Treat users as capable adults. Do not over-explain.            |
+| **Calm**       | Even error messages stay composed. The interface never panics. |
 
 The voice is never casual, never corporate, never clever, never apologetic.
 
@@ -42,14 +42,14 @@ Do not write: "Something went wrong", "Error", "Invalid input".
 
 Do not use these phrases anywhere in the interface:
 
-| Phrase | Instead |
-|---|---|
-| "Click here" | Describe the action |
-| "Please" | Direct language is respectful |
-| "Sorry" | Fix the problem |
-| "Successfully" | Just state the result: "Entry published" |
+| Phrase          | Instead                                                          |
+| --------------- | ---------------------------------------------------------------- |
+| "Click here"    | Describe the action                                              |
+| "Please"        | Direct language is respectful                                    |
+| "Sorry"         | Fix the problem                                                  |
+| "Successfully"  | Just state the result: "Entry published"                         |
 | "Are you sure?" | State what will happen: "This will permanently delete the entry" |
-| "Learn more" | Link to the specific topic |
+| "Learn more"    | Link to the specific topic                                       |
 
 ## Confirmation dialogs
 
@@ -65,7 +65,7 @@ Never use "Cancel", "Go back", or "No" as the cancel label.
 ## Notifications
 
 - Active voice, present tense: "Entry published"
-- Max 1–2 sentences
+- Max 1-2 sentences
 - Auto-dismiss after 6 seconds unless error
 
 ## Tooltips
@@ -76,11 +76,11 @@ Never use "Cancel", "Go back", or "No" as the cancel label.
 
 ## Status labels
 
-| Status | Label |
-|---|---|
-| Published and current | "Published" |
-| Published with changes | "Changed" |
-| Never published | "Draft" |
-| Removed from publication | "Archived" |
+| Status                   | Label       |
+| ------------------------ | ----------- |
+| Published and current    | "Published" |
+| Published with changes   | "Changed"   |
+| Never published          | "Draft"     |
+| Removed from publication | "Archived"  |
 
 Do not invent custom status labels for standard Contentful entity states.
diff --git a/skills/guidelines/setup.md b/skills/guidelines/setup.md
index 73e7d29a87..5e675c63ae 100644
--- a/skills/guidelines/setup.md
+++ b/skills/guidelines/setup.md
@@ -40,7 +40,7 @@ Import tokens for use in inline styles and custom CSS:
 import tokens from '@contentful/f36-tokens';
 
 // Use in inline styles
-<div style={{ padding: tokens.spacingM, color: tokens.colorPrimary }} />
+<div style={{ padding: tokens.spacingM, color: tokens.colorPrimary }} />;
 
 // Or import individual tokens
 import { spacingM, colorPrimary } from '@contentful/f36-tokens';
@@ -53,7 +53,11 @@ Do not hardcode hex values, pixel measurements, or font stacks. Always use the t
 All icons come from the Phosphor library, packaged in `@contentful/f36-icons`:
 
 ```tsx
-import { PlusIcon, SearchIcon, DeleteIcon } from '@contentful/f36-icons';
+import {
+  PlusIcon,
+  MagnifyingGlassIcon,
+  TrashSimpleIcon,
+} from '@contentful/f36-icons';
 ```
 
 Do not use Material Icons, Heroicons, Feather, Lucide, or any other icon library.
diff --git a/skills/guidelines/tokens/color.md b/skills/guidelines/tokens/color.md
index d3682489a6..8751414000 100644
--- a/skills/guidelines/tokens/color.md
+++ b/skills/guidelines/tokens/color.md
@@ -6,12 +6,12 @@ Color in Forma 36 carries meaning. It is never decorative.
 
 Ask yourself: **what does this color communicate?**
 
-- Primary interactive action → Blue
-- Success or published state → Green
-- Danger, error, or destructive action → Red
-- Warning or draft/unpublished state → Orange
-- Premium or paid feature → Purple (use sparingly)
-- Neutral surface or text → Gray scale
+- Primary interactive action -> Blue
+- Success or published state -> Green
+- Danger, error, or destructive action -> Red
+- Warning or draft/unpublished state -> Orange
+- Premium or paid feature -> Purple (use sparingly)
+- Neutral surface or text -> Gray scale
 
 If the answer is "it looks nice" — do not use that color. Use gray or white instead.
 
@@ -19,92 +19,97 @@ If the answer is "it looks nice" — do not use that color. Use gray or white in
 
 These express intent, not shade. Reach for them by default.
 
-| Token | Hex | Use |
-|---|---|---|
-| `colorPrimary` | `#0059C8` | Primary interactive actions, links |
+| Token           | Hex       | Use                                            |
+| --------------- | --------- | ---------------------------------------------- |
+| `colorPrimary`  | `#0059C8` | Primary interactive actions, links             |
 | `colorPositive` | `#006D23` | Success, published state, constructive actions |
-| `colorNegative` | `#BD002A` | Errors, destructive actions, deleted state |
-| `colorWarning` | `#CC4500` | Warnings, draft/unpublished state |
+| `colorNegative` | `#BD002A` | Errors, destructive actions, deleted state     |
+| `colorWarning`  | `#CC4500` | Warnings, draft/unpublished state              |
 
 ## Text color tokens
 
-| Token | Hex | Use |
-|---|---|---|
-| `colorTextDark` | `#111B2B` | Highest-contrast text — headings, primary labels |
-| `colorTextBase` | `#1B273A` | Default body text |
-| `colorTextMid` | `#414D63` | Secondary labels, section titles |
-| `colorTextLight` | `#5A657C` | Tertiary text, captions, hints |
-| `colorTextLightest` | `#67728A` | Placeholder text, inactive labels |
+| Token               | Hex       | Use                                              |
+| ------------------- | --------- | ------------------------------------------------ |
+| `colorTextDark`     | `#111B2B` | Highest-contrast text — headings, primary labels |
+| `colorTextBase`     | `#1B273A` | Default body text                                |
+| `colorTextMid`      | `#414D63` | Secondary labels, section titles                 |
+| `colorTextLight`    | `#5A657C` | Tertiary text, captions, hints                   |
+| `colorTextLightest` | `#67728A` | Placeholder text, inactive labels                |
 
 ## Gray scale
 
-| Token | Hex | Use |
-|---|---|---|
-| `gray100` | `#F7F9FA` | Page background |
-| `gray200` | `#E7EBEE` | Dividers, subtle borders |
-| `gray300` | `#CFD9E0` | Input outlines, borders |
-| `gray400` | `#AEC1CC` | Disabled borders |
+| Token     | Hex       | Use                           |
+| --------- | --------- | ----------------------------- |
+| `gray100` | `#F7F9FA` | Page background               |
+| `gray200` | `#E7EBEE` | Dividers, subtle borders      |
+| `gray300` | `#CFD9E0` | Input outlines, borders       |
+| `gray400` | `#AEC1CC` | Disabled borders              |
 | `gray500` | `#67728A` | Muted icons, placeholder text |
-| `gray600` | `#5A657C` | Muted/secondary icons |
-| `gray700` | `#414D63` | Section heading text |
-| `gray800` | `#1B273A` | Strong secondary text |
-| `gray900` | `#111B2B` | Primary text, nav labels |
+| `gray600` | `#5A657C` | Muted/secondary icons         |
+| `gray700` | `#414D63` | Section heading text          |
+| `gray800` | `#1B273A` | Strong secondary text         |
+| `gray900` | `#111B2B` | Primary text, nav labels      |
 
 ## Blue (primary)
 
-| Token | Hex | Use |
-|---|---|---|
-| `blue100` | `#E8F5FF` | Active nav item background |
-| `blue200` | `#CEECFF` | Hover on primary elements |
+| Token     | Hex       | Use                                           |
+| --------- | --------- | --------------------------------------------- |
+| `blue100` | `#E8F5FF` | Active nav item background                    |
+| `blue200` | `#CEECFF` | Hover on primary elements                     |
+| `blue300` | `#98CBFF` | —                                             |
+| `blue400` | `#40A0FF` | —                                             |
+| `blue500` | `#036FE3` | —                                             |
 | `blue600` | `#0059C8` | Primary action — buttons, links, active icons |
-| `blue700` | `#0041AB` | Pressed state |
+| `blue700` | `#0041AB` | Pressed state                                 |
+| `blue800` | `#003298` | —                                             |
+| `blue900` | `#002A8E` | —                                             |
 
 ## Green (positive)
 
-| Token | Hex | Use |
-|---|---|---|
+| Token      | Hex       | Use                             |
+| ---------- | --------- | ------------------------------- |
 | `green100` | `#EAF9E8` | Environment switcher background |
-| `green300` | `#9ED696` | Environment indicator strip |
-| `green400` | `#5DB057` | Environment switcher border |
-| `green600` | `#006D23` | Published status, success text |
-| `green700` | `#00550C` | Environment switcher text |
+| `green300` | `#9ED696` | Environment indicator strip     |
+| `green400` | `#5DB057` | Environment switcher border     |
+| `green600` | `#006D23` | Published status, success text  |
+| `green700` | `#00550C` | Environment switcher text       |
 
 ## Red (negative)
 
-| Token | Hex | Use |
-|---|---|---|
-| `red100` | `#FFF2F2` | Error field background |
+| Token    | Hex       | Use                             |
+| -------- | --------- | ------------------------------- |
+| `red100` | `#FFF2F2` | Error field background          |
 | `red600` | `#BD002A` | Error text, destructive buttons |
-| `red700` | `#990017` | Pressed destructive state |
+| `red700` | `#990017` | Pressed destructive state       |
 
 ## Orange (warning)
 
-| Token | Hex | Use |
-|---|---|---|
-| `orange100` | `#FFF2E4` | Warning note background |
-| `orange400` | `#F07F23` | Warning icons |
+| Token       | Hex       | Use                                   |
+| ----------- | --------- | ------------------------------------- |
+| `orange100` | `#FFF2E4` | Warning note background               |
+| `orange400` | `#F07F23` | Warning icons                         |
 | `orange500` | `#CC4500` | Draft/unpublished state, warning text |
 
 ## Purple (premium — use sparingly)
 
-| Token | Hex | Use |
-|---|---|---|
-| `purple100` | `#F7F2FF` | Premium feature background |
-| `purple500` | `#8553E7` | Premium icons |
+| Token       | Hex       | Use                                    |
+| ----------- | --------- | -------------------------------------- |
+| `purple100` | `#F7F2FF` | Premium feature background             |
+| `purple500` | `#8553E7` | Premium icons                          |
 | `purple600` | `#6C3ECF` | Premium label, "new feature" highlight |
 
 ## Yellow (last resort)
 
-| Token | Hex |
-|---|---|
-| `yellow400` | `#FFC835` |
+| Token       | Hex       |
+| ----------- | --------- |
+| `yellow400` | `#FFD960` |
 
 Only use yellow when no other color communicates the meaning. This is rare.
 
 ## Absolute
 
-| Token | Hex |
-|---|---|
+| Token        | Hex       |
+| ------------ | --------- |
 | `colorWhite` | `#FFFFFF` |
 | `colorBlack` | `#0C141C` |
 
diff --git a/skills/guidelines/tokens/effects.md b/skills/guidelines/tokens/effects.md
index 1f1edf9061..d29666f64f 100644
--- a/skills/guidelines/tokens/effects.md
+++ b/skills/guidelines/tokens/effects.md
@@ -4,12 +4,12 @@ Shadows, border radius, z-index, transitions, and focus rings.
 
 ## Shadows
 
-| Token | CSS value | Use |
-|---|---|---|
-| `shadowDefault` | `0px 0px 0px 1px rgba(25,37,50,.10), 0px 3px 7px -3px rgba(25,37,50,.10), 0px 6px 12px -2px rgba(25,37,50,.10)` | Panels, sidebar, content area, cards |
-| `shadowHeavy` | `0px 0px 0px 1px rgba(25,37,50,.10), 0px -6px 16px -6px rgba(25,37,50,.03), 0px 8px 16px -8px rgba(25,37,50,.20), 0px 13px 27px -5px rgba(25,37,50,.15)` | Elevated modals, popovers |
-| `shadowButton` | `0px 1px 0px rgb(25,37,50,.10)` | Secondary and transparent buttons |
-| `insetBoxShadowDefault` | `inset 0px 2px 0px rgba(225,228,232,.20)` | Pressed/active input states |
+| Token                   | CSS value                                                                                                                                                | Use                                  |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
+| `boxShadowDefault`      | `0px 0px 0px 1px rgba(25,37,50,.10), 0px 3px 7px -3px rgba(25,37,50,.10), 0px 6px 12px -2px rgba(25,37,50,.10)`                                          | Panels, sidebar, content area, cards |
+| `boxShadowHeavy`        | `0px 0px 0px 1px rgba(25,37,50,.10), 0px -6px 16px -6px rgba(25,37,50,.03), 0px 8px 16px -8px rgba(25,37,50,.20), 0px 13px 27px -5px rgba(25,37,50,.15)` | Elevated modals, popovers            |
+| `boxShadowPositive`     | `0px 1px 0px rgb(25,37,50,.10)`                                                                                                                          | Secondary and transparent buttons    |
+| `insetBoxShadowDefault` | `inset 0px 2px 0px rgba(225,228,232,.20)`                                                                                                                | Pressed/active input states          |
 
 Do not invent custom shadows. These four values are all that exist.
 
@@ -17,13 +17,13 @@ Do not invent custom shadows. These four values are all that exist.
 
 Applied on `:focus-visible` for accessible focus indicators.
 
-| Token | Use |
-|---|---|
-| `glowPrimary` | Primary input/button focus |
-| `glowNegative` | Error input focus |
-| `glowPositive` | Success input focus |
-| `glowWarning` | Warning input focus |
-| `glowMuted` | Neutral focus |
+| Token          | Use                        |
+| -------------- | -------------------------- |
+| `glowPrimary`  | Primary input/button focus |
+| `glowNegative` | Error input focus          |
+| `glowPositive` | Success input focus        |
+| `glowWarning`  | Warning input focus        |
+| `glowMuted`    | Neutral focus              |
 
 All glow tokens render as `0px 0px 0px 3px` with a color-appropriate light shade.
 
@@ -31,17 +31,17 @@ All glow tokens render as `0px 0px 0px 3px` with a color-appropriate light shade
 
 Only two values are exported as tokens:
 
-| Token | Value | Use |
-|---|---|---|
-| `borderRadiusSmall` | 4px | Nav items, badges, small chips |
-| `borderRadiusMedium` | 6px | Buttons, inputs, menus |
+| Token                | Value | Use                            |
+| -------------------- | ----- | ------------------------------ |
+| `borderRadiusSmall`  | 4px   | Nav items, badges, small chips |
+| `borderRadiusMedium` | 6px   | Buttons, inputs, menus         |
 
 Design conventions (not exported tokens — use inline styles):
 
-| Value | Use |
-|---|---|
-| `12px` | Panels, cards, modals, sidebar |
-| `100px` | Avatars, pill-shaped elements |
+| Value   | Use                            |
+| ------- | ------------------------------ |
+| `12px`  | Panels, cards, modals, sidebar |
+| `100px` | Avatars, pill-shaped elements  |
 
 Top-only radius for panels flush to the bottom: `border-radius: 12px 12px 0 0`.
 
@@ -49,24 +49,24 @@ Do not use rounded corners outside this set: 4px, 6px, 12px, 100px.
 
 ## Z-index
 
-| Token | Value | Use |
-|---|---|---|
-| `zIndexNegative` | -1 | Behind-everything layer |
-| `zIndexWorkbench` | 0 | Page base layer |
-| `zIndexDefault` | 1 | Normal stacking |
-| `zIndexWorkbenchHeader` | 10 | Sticky headers |
-| `zIndexModal` | 100 | Modals, dialogs |
-| `zIndexModalContent` | 101 | Modal content above overlay |
-| `zIndexDropdown` | 1000 | Menus, dropdowns |
-| `zIndexTooltip` | 10000 | Tooltips |
-| `zIndexNotification` | 100000 | Toast notifications |
+| Token                   | Value  | Use                         |
+| ----------------------- | ------ | --------------------------- |
+| `zIndexNegative`        | -1     | Behind-everything layer     |
+| `zIndexWorkbench`       | 0      | Page base layer             |
+| `zIndexDefault`         | 1      | Normal stacking             |
+| `zIndexWorkbenchHeader` | 10     | Sticky headers              |
+| `zIndexModal`           | 100    | Modals, dialogs             |
+| `zIndexModalContent`    | 101    | Modal content above overlay |
+| `zIndexDropdown`        | 1000   | Menus, dropdowns            |
+| `zIndexTooltip`         | 10000  | Tooltips                    |
+| `zIndexNotification`    | 100000 | Toast notifications         |
 
 ## Transitions
 
-| Token | Value | Use |
-|---|---|---|
-| `transitionDurationShort` | 0.1s | Micro interactions (hover, focus ring) |
-| `transitionDurationDefault` | 0.2s | Standard transitions (collapse, fade) |
-| `transitionDurationLong` | 0.3s | Larger movements (sidebar, modal) |
-| `transitionEasingDefault` | ease-in-out | Default easing |
-| `transitionEasingCubicBezier` | cubic-bezier(0.13, 0.62, 0.11, 0.99) | Spring-like emphasis |
+| Token                         | Value                                | Use                                    |
+| ----------------------------- | ------------------------------------ | -------------------------------------- |
+| `transitionDurationShort`     | 0.1s                                 | Micro interactions (hover, focus ring) |
+| `transitionDurationDefault`   | 0.2s                                 | Standard transitions (collapse, fade)  |
+| `transitionDurationLong`      | 0.3s                                 | Larger movements (sidebar, modal)      |
+| `transitionEasingDefault`     | ease-in-out                          | Default easing                         |
+| `transitionEasingCubicBezier` | cubic-bezier(0.13, 0.62, 0.11, 0.99) | Spring-like emphasis                   |
diff --git a/skills/guidelines/tokens/overview.md b/skills/guidelines/tokens/overview.md
index 7678fa0c0a..47c2f49786 100644
--- a/skills/guidelines/tokens/overview.md
+++ b/skills/guidelines/tokens/overview.md
@@ -11,15 +11,16 @@ import tokens from '@contentful/f36-tokens';
 Tokens are the single source of truth for every visual property. They ensure consistency across components, screens, and contributors. When you use a token, the design system can evolve without breaking your code.
 
 **Rules:**
+
 - Do not hardcode hex colors, pixel values, font sizes, or shadow strings
 - If a value exists as a token, use the token
 - If no token exists for the value you need, the value is probably wrong — check the design
 
 ## Token groups
 
-| File | What it covers |
-|---|---|
-| `color.md` | Semantic colors, gray scale, blue/green/red/orange/purple/yellow palettes |
-| `typography.md` | Font families, sizes, weights, line heights, letter spacing |
-| `spacing.md` | The spacing scale (4px–80px) and how to apply it |
-| `effects.md` | Shadows, border radius, z-index, transitions, focus rings |
+| File            | What it covers                                                            |
+| --------------- | ------------------------------------------------------------------------- |
+| `color.md`      | Semantic colors, gray scale, blue/green/red/orange/purple/yellow palettes |
+| `typography.md` | Font families, sizes, weights, line heights, letter spacing               |
+| `spacing.md`    | The spacing scale (4px-80px) and how to apply it                          |
+| `effects.md`    | Shadows, border radius, z-index, transitions, focus rings                 |
diff --git a/skills/guidelines/tokens/spacing.md b/skills/guidelines/tokens/spacing.md
index 1b7c70cc2d..b697f35abb 100644
--- a/skills/guidelines/tokens/spacing.md
+++ b/skills/guidelines/tokens/spacing.md
@@ -4,23 +4,24 @@ Spacing follows a fixed scale. Use these values only — never arbitrary pixel v
 
 ## The scale
 
-| Token | Value | Rem | Use |
-|---|---|---|---|
-| `spacing2Xs` | 4px | 0.25rem | Icon gaps, tight groupings |
-| `spacingXs` | 8px | 0.5rem | Between related items |
-| `spacingS` | 12px | 0.75rem | Component internal padding |
-| `spacingM` | 16px | 1rem | Standard padding |
-| `spacingL` | 24px | 1.5rem | Section padding |
-| `spacingXl` | 32px | 2rem | Large section gaps |
-| `spacing2Xl` | 48px | 3rem | Page-level separation |
-| `spacing3Xl` | 64px | 4rem | Large page gaps |
-| `spacing4Xl` | 80px | 5rem | Maximum spacing |
+| Token        | Value | Rem     | Use                        |
+| ------------ | ----- | ------- | -------------------------- |
+| `spacing2Xs` | 4px   | 0.25rem | Icon gaps, tight groupings |
+| `spacingXs`  | 8px   | 0.5rem  | Between related items      |
+| `spacingS`   | 12px  | 0.75rem | Component internal padding |
+| `spacingM`   | 16px  | 1rem    | Standard padding           |
+| `spacingL`   | 24px  | 1.5rem  | Section padding            |
+| `spacingXl`  | 32px  | 2rem    | Large section gaps         |
+| `spacing2Xl` | 48px  | 3rem    | Page-level separation      |
+| `spacing3Xl` | 64px  | 4rem    | Large page gaps            |
+| `spacing4Xl` | 80px  | 5rem    | Maximum spacing            |
 
 ## How to apply spacing
 
 Components carry no external margin by default. Use layout wrappers or inline tokens.
 
 **Layout component props:**
+
 ```tsx
 <Stack spacing="spacingM" />
 <Flex gap="spacingS" />
@@ -28,24 +29,25 @@ Components carry no external margin by default. Use layout wrappers or inline to
 ```
 
 **Inline styles (when layout props are insufficient):**
+
 ```tsx
 <div style={{ padding: tokens.spacingM, gap: tokens.spacingS }} />
 ```
 
 ## Choosing the right spacing
 
-- Between items in a group (buttons, badges) → `spacingXs` (8px)
-- Internal padding of a component → `spacingS` (12px) or `spacingM` (16px)
-- Between sections on a page → `spacingL` (24px) or `spacingXl` (32px)
-- Page-level top/bottom margins → `spacing2Xl` (48px)
+- Between items in a group (buttons, badges) -> `spacingXs` (8px)
+- Internal padding of a component -> `spacingS` (12px) or `spacingM` (16px)
+- Between sections on a page -> `spacingL` (24px) or `spacingXl` (32px)
+- Page-level top/bottom margins -> `spacing2Xl` (48px)
 
 ## Content width tokens
 
-| Token | Value | Use |
-|---|---|---|
+| Token                 | Value  | Use                                               |
+| --------------------- | ------ | ------------------------------------------------- |
 | `contentWidthDefault` | 1280px | Standard page max-width (`Layout variant="wide"`) |
-| `contentWidthText` | 768px | Narrow content (`Layout variant="narrow"`, forms) |
-| `contentWidthFull` | 100% | Fullscreen (`Layout variant="fullscreen"`) |
+| `contentWidthText`    | 768px  | Narrow content (`Layout variant="narrow"`, forms) |
+| `contentWidthFull`    | 100%   | Fullscreen (`Layout variant="fullscreen"`)        |
 
 ## Rules
 
diff --git a/skills/guidelines/tokens/typography.md b/skills/guidelines/tokens/typography.md
index abf9b88457..7ba0ff683a 100644
--- a/skills/guidelines/tokens/typography.md
+++ b/skills/guidelines/tokens/typography.md
@@ -4,48 +4,48 @@ The typeface is **Geist** by Vercel. Always use composite type classes — do no
 
 ## Font families
 
-| Token | Stack |
-|---|---|
-| `fontStackPrimary` | `Geist Sans, -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial, sans-serif` |
-| `fontStackMonospace` | `Geist Mono, SFMono-Regular, Consolas, Liberation Mono, Menlo, monospace` |
+| Token                | Stack                                                                                   |
+| -------------------- | --------------------------------------------------------------------------------------- |
+| `fontStackPrimary`   | `Geist Sans, -apple-system, BlinkMacSystemFont, Segoe UI, Helvetica, Arial, sans-serif` |
+| `fontStackMonospace` | `Geist Mono, SFMono-Regular, Consolas, Liberation Mono, Menlo, monospace`               |
 
 Always use `fontStackPrimary`. Never hardcode `"Geist"` without the fallback stack. Load the font from `https://cdn.f36.contentful.com`.
 
 ## Font sizes
 
-| Token | Value | Use |
-|---|---|---|
-| `fontSize4Xl` | 3rem | Hero display text |
-| `fontSize3Xl` | 2.25rem | Large display |
-| `fontSize2Xl` | 1.5rem | Page-level headings |
-| `fontSizeXl` | 1.25rem | Section headings |
-| `fontSizeL` | 1rem | Large body |
-| `fontSizeM` | 0.875rem | **Default body** — most interface text |
-| `fontSizeS` | 0.75rem | Captions, metadata, section labels |
+| Token         | Value    | Use                                    |
+| ------------- | -------- | -------------------------------------- |
+| `fontSize4Xl` | 3rem     | Hero display text                      |
+| `fontSize3Xl` | 2.25rem  | Large display                          |
+| `fontSize2Xl` | 1.5rem   | Page-level headings                    |
+| `fontSizeXl`  | 1.25rem  | Section headings                       |
+| `fontSizeL`   | 1rem     | Large body                             |
+| `fontSizeM`   | 0.875rem | **Default body** — most interface text |
+| `fontSizeS`   | 0.75rem  | Captions, metadata, section labels     |
 
 ## Font weights
 
-| Token | Value | Use |
-|---|---|---|
-| `fontWeightNormal` | 400 | All body text |
-| `fontWeightMedium` | 500 | Emphasized labels, active states |
-| `fontWeightDemiBold` | 600 | Headings, section titles, nav group labels |
+| Token                | Value | Use                                        |
+| -------------------- | ----- | ------------------------------------------ |
+| `fontWeightNormal`   | 400   | All body text                              |
+| `fontWeightMedium`   | 500   | Emphasized labels, active states           |
+| `fontWeightDemiBold` | 600   | Headings, section titles, nav group labels |
 
 Do not use `700` (bold) or `300` (light). Forma 36 uses only these three weights.
 
 ## Line heights
 
-| Token | Value | Use |
-|---|---|---|
-| `lineHeightDefault` | 1.5 | Body text |
-| `lineHeightCondensed` | 1.25 | Nav items, badges, compact UI |
+| Token                 | Value | Use                           |
+| --------------------- | ----- | ----------------------------- |
+| `lineHeightDefault`   | 1.5   | Body text                     |
+| `lineHeightCondensed` | 1.25  | Nav items, badges, compact UI |
 
 ## Letter spacing
 
-| Token | Value |
-|---|---|
-| `letterSpacingDefault` | 0rem |
-| `letterSpacingWide` | 0.1rem |
+| Token                  | Value  |
+| ---------------------- | ------ |
+| `letterSpacingDefault` | 0rem   |
+| `letterSpacingWide`    | 0.1rem |
 
 Forma 36 uses `0` letter spacing by default. Do not add tracking to Geist.
 
@@ -53,22 +53,24 @@ Forma 36 uses `0` letter spacing by default. Do not add tracking to Geist.
 
 When implementing text, combine tokens like this:
 
-| Role | Size | Weight | Line height | Use |
-|---|---|---|---|---|
-| Display | `fontSize2Xl`+ | `fontWeightDemiBold` | `lineHeightDefault` | Page titles, hero text |
-| Section heading | `fontSizeS` | `fontWeightDemiBold` | `lineHeightCondensed` | Nav group labels, table headers |
-| Body (default) | `fontSizeM` | `fontWeightNormal` | `lineHeightDefault` | All interface copy |
-| Body medium | `fontSizeM` | `fontWeightMedium` | `lineHeightDefault` | Emphasized labels |
-| Small / caption | `fontSizeS` | `fontWeightNormal` | `lineHeightDefault` | Metadata, hints |
+| Role            | Size           | Weight               | Line height           | Use                             |
+| --------------- | -------------- | -------------------- | --------------------- | ------------------------------- |
+| Display         | `fontSize2Xl`+ | `fontWeightDemiBold` | `lineHeightDefault`   | Page titles, hero text          |
+| Section heading | `fontSizeS`    | `fontWeightDemiBold` | `lineHeightCondensed` | Nav group labels, table headers |
+| Body (default)  | `fontSizeM`    | `fontWeightNormal`   | `lineHeightDefault`   | All interface copy              |
+| Body medium     | `fontSizeM`    | `fontWeightMedium`   | `lineHeightDefault`   | Emphasized labels               |
+| Small / caption | `fontSizeS`    | `fontWeightNormal`   | `lineHeightDefault`   | Metadata, hints                 |
 
 ## High-density variants
 
 For compact UI contexts (dense tables, toolbar items):
 
-| Token | Value | Use |
-|---|---|---|
-| `fontSizeMHigh` | 0.75rem | Dense body (= default `fontSizeS`) |
-| `fontSizeSHigh` | 0.625rem | Dense caption |
+| Token            | Value    | Use                                      |
+| ---------------- | -------- | ---------------------------------------- |
+| `fontSizeXlHigh` | 1.125rem | Dense heading                            |
+| `fontSizeLHigh`  | 0.875rem | Dense large body (= default `fontSizeM`) |
+| `fontSizeMHigh`  | 0.75rem  | Dense body (= default `fontSizeS`)       |
+| `fontSizeSHigh`  | 0.625rem | Dense caption                            |
 
 ## Rules
 

From 413318d9016f600f65284e3b26873b55e0785df1 Mon Sep 17 00:00:00 2001
From: toniwowtscherk <toni.wowtscherk@contentful.com>
Date: Wed, 29 Apr 2026 11:32:20 +0200
Subject: [PATCH 10/13] docs: add visual verification loop for Path C + sync
 eval fixes

Adds screenshot comparison post-flight for Figma-to-code (Path C):
capture source Figma design, render generated code, compare both,
fix differences until converging. Eval showed V3 Path C missed sidebar,
top nav, filter chips, and avatar columns because the design context
alone doesn't describe page-level composition.

Also syncs eval-driven fixes from product-design PR #7: corrected icon
names (TrashIcon not TrashSimpleIcon), removed fabricated Skeleton.Row,
fixed shadow token names.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 skills/SKILL.md                               |  57 +++++++---
 skills/guidelines/composition/overview.md     |   9 +-
 .../composition/visual-verification.md        | 105 ++++++++++++++++++
 3 files changed, 151 insertions(+), 20 deletions(-)
 create mode 100644 skills/guidelines/composition/visual-verification.md

diff --git a/skills/SKILL.md b/skills/SKILL.md
index b91d55c183..e2508c9f56 100644
--- a/skills/SKILL.md
+++ b/skills/SKILL.md
@@ -24,10 +24,10 @@ Forma 36 is the design language of Contentful. Every screen, component, and inte
 ```
 REQUIRED  import '@contentful/f36-components/dist/styles.css'  — without this, all components render unstyled
 REQUIRED  Every component has an explicit import from @contentful/f36-components or @contentful/f36-icons
-REQUIRED  All icon names come from @contentful/f36-icons (Phosphor set) — see guidelines/foundations/icons.md for the approved list. NEVER invent icon names. Common: DotsThreeIcon (menus), TrashSimpleIcon (delete), PencilSimpleIcon (edit), GearSixIcon (settings), PlusIcon, MagnifyingGlassIcon (search), XIcon (close), CheckIcon, WarningIcon, ArrowLeftIcon.
+REQUIRED  All icon names come from @contentful/f36-icons (Phosphor set) — see guidelines/foundations/icons.md for the approved list. NEVER invent icon names. Common: DotsThreeIcon (menus), TrashIcon (delete), PencilIcon (edit), GearIcon (settings), PlusIcon, SearchIcon, CloseIcon, CheckIcon, WarningIcon, ArrowLeftIcon.
 REQUIRED  All colors, spacing, typography use @contentful/f36-tokens — NEVER hardcode hex, px, or font stacks
 REQUIRED  Use Layout (not Workbench) as the page shell. Layout.Header, Layout.Body, Layout.Sidebar are REAL compound sub-components (verified in source) — use them confidently. These are the ONLY valid sub-components.
-REQUIRED  Skeleton sub-components: Skeleton.Container, Skeleton.DisplayText, Skeleton.BodyText, Skeleton.Image, Skeleton.Row (for table loading: rowCount, columnCount props). There is no Skeleton.Table or Skeleton.Cell.
+REQUIRED  Skeleton sub-components: Skeleton.Container, Skeleton.DisplayText, Skeleton.BodyText, Skeleton.Image — these are the ONLY valid sub-components. There is NO Skeleton.Row.
 ```
 
 ---
@@ -106,6 +106,30 @@ A Figma URL is present. The goal is to translate Figma designs into production c
 - **239 icons** connected in the Forma 36 Assets Figma file
 - See `guidelines/code-connect.md` for the complete mapping table
 
+**Visual verification (post-flight for Path C):**
+
+Code Connect maps individual components but does NOT describe page-level composition — sidebar presence, top nav structure, filter chip patterns, avatar columns, or layout hierarchy. The design context alone is often incomplete. You MUST visually verify.
+
+After generating code from a Figma design context:
+
+1. **Screenshot the source** — call `get_screenshot(fileKey, nodeId)` to capture the original Figma design
+2. **Render your output** — start a local dev server and open the generated page
+3. **Screenshot your output** — use Playwright MCP `browser_take_screenshot` to capture the rendered page
+4. **Compare both screenshots.** Systematically check for:
+   - Missing navigation (top bar, sidebar, breadcrumbs, nav items)
+   - Missing or extra table/list columns (avatars, workflows, icons)
+   - Different filter patterns (chips vs dropdowns, filter bar layout)
+   - Missing UI elements (content type icons next to entries, avatars, badges)
+   - Layout structure differences (sidebar vs no sidebar, narrow vs wide)
+   - Data format mismatches (relative vs absolute dates, "by Author" attribution)
+   - Missing page-level chrome (space/environment pill, search icon, settings icon)
+5. **Fix every difference** — update the code to match the source design
+6. **Re-render and re-compare** until the output faithfully matches the source
+
+This loop typically converges in 1–2 iterations. The first comparison catches structural gaps (missing sidebar, missing columns); the second catches detail gaps (wrong date format, missing icons).
+
+See `guidelines/composition/visual-verification.md` for the detailed checklist.
+
 ### Path D — Code to Figma design (writing to Figma via MCP)
 
 You have existing code, a running prototype, or a component implementation and want to push it into a Figma file as a design. This uses the Figma MCP server's write capabilities.
@@ -211,7 +235,7 @@ These apply to all paths. Do not override them.
 - **Phosphor icons only** — never Material, Heroicons, Feather, or Lucide.
 - **"Never mind"** — the cancel label for destructive confirmations. Not "Cancel".
 - **`Layout` not `Workbench`** — Workbench is deprecated.
-- **No custom shadows** — only `boxShadowDefault`, `boxShadowHeavy`, `boxShadowPositive`, `insetBoxShadowDefault`.
+- **No custom shadows** — only `shadowDefault`, `shadowHeavy`, `shadowButton`, `insetBoxShadowDefault`.
 - **No border radius outside the scale** — 4px, 6px, 12px, 100px only.
 
 ---
@@ -299,11 +323,12 @@ Each folder contains an `overview.md` that indexes its contents.
 
 ### `guidelines/composition/`
 
-| File                 | What it covers                                                                                      |
-| -------------------- | --------------------------------------------------------------------------------------------------- |
-| `overview.md`        | Composition philosophy and file index                                                               |
-| `base-shell.md`      | Standard app chrome — top bar (52px), sidebar (240px), content area                                 |
-| `screen-patterns.md` | 9 named patterns: list, detail, settings, empty state, error, confirmation, wizard, dashboard, form |
+| File                     | What it covers                                                                                      |
+| ------------------------ | --------------------------------------------------------------------------------------------------- |
+| `overview.md`            | Composition philosophy and file index                                                               |
+| `base-shell.md`          | Standard app chrome — top bar (52px), sidebar (240px), content area                                 |
+| `screen-patterns.md`     | 9 named patterns: list, detail, settings, empty state, error, confirmation, wizard, dashboard, form |
+| `visual-verification.md` | Figma-to-code post-flight — screenshot comparison loop to catch missing page-level elements         |
 
 ### `guidelines/foundations/`
 
@@ -318,14 +343,14 @@ Each folder contains an `overview.md` that indexes its contents.
 
 Working TSX files demonstrating correct usage. Each maps to a screen pattern.
 
-| File                     | Pattern         | What it shows                                                                        |
-| ------------------------ | --------------- | ------------------------------------------------------------------------------------ |
-| `list-page.tsx`          | List / Index    | Table, search, EntityStatusBadge, Menu actions, Pagination, empty state, Skeleton    |
-| `detail-page.tsx`        | Detail / Edit   | Right sidebar, breadcrumbs, form validation, unsaved-changes Note                    |
-| `settings-page.tsx`      | Settings        | Grouped sections, Switch toggles, danger zone                                        |
-| `confirmation-modal.tsx` | Confirmation    | Modal, "Never mind" cancel, `isLoading` confirm, `shouldCloseOnOverlayClick={false}` |
-| `form-page.tsx`          | Standalone Form | `Layout variant="narrow"`, grouped FormControls, Accordion, Notification             |
-| `error-state.tsx`        | Error State     | Centered error, WarningOctagonIcon, "Try again" + "Go back"                          |
+| File                      | Pattern         | What it shows                                                                        |
+| ------------------------- | --------------- | ------------------------------------------------------------------------------------ |
+| `list-page.tsx`           | List / Index    | Table, search, EntityStatusBadge, Menu actions, Pagination, empty state, Skeleton    |
+| `detail-page.tsx`         | Detail / Edit   | Right sidebar, breadcrumbs, form validation, unsaved-changes Note                    |
+| `settings-page.tsx`       | Settings        | Grouped sections, Switch toggles, danger zone                                        |
+| `confirmation-dialog.tsx` | Confirmation    | Modal, "Never mind" cancel, `isLoading` confirm, `shouldCloseOnOverlayClick={false}` |
+| `form-page.tsx`           | Standalone Form | `Layout variant="narrow"`, grouped FormControls, Accordion, Notification             |
+| `error-state.tsx`         | Error State     | Centered error, WarningOctagonIcon, "Try again" + "Go back"                          |
 
 ---
 
diff --git a/skills/guidelines/composition/overview.md b/skills/guidelines/composition/overview.md
index ba8c65e7b9..8380353b14 100644
--- a/skills/guidelines/composition/overview.md
+++ b/skills/guidelines/composition/overview.md
@@ -4,10 +4,11 @@ This section covers how to assemble components into complete screens. Every Cont
 
 ## Files
 
-| File | What it covers |
-|---|---|
-| `base-shell.md` | The standard app chrome — top bar, sidebar, content area |
-| `screen-patterns.md` | Named patterns: list, detail, settings, empty state, error, confirmation, wizard, dashboard, form |
+| File                     | What it covers                                                                                    |
+| ------------------------ | ------------------------------------------------------------------------------------------------- |
+| `base-shell.md`          | The standard app chrome — top bar, sidebar, content area                                          |
+| `screen-patterns.md`     | Named patterns: list, detail, settings, empty state, error, confirmation, wizard, dashboard, form |
+| `visual-verification.md` | Figma-to-code post-flight — screenshot comparison loop to catch missing page elements             |
 
 ## Rule
 
diff --git a/skills/guidelines/composition/visual-verification.md b/skills/guidelines/composition/visual-verification.md
new file mode 100644
index 0000000000..a7c14de1e7
--- /dev/null
+++ b/skills/guidelines/composition/visual-verification.md
@@ -0,0 +1,105 @@
+# Visual Verification — Figma-to-Code Post-Flight
+
+When translating a Figma design to code (Path C), the design context from `get_design_context` gives you component-level Code Connect snippets but often misses page-level structure. This verification loop ensures the generated code faithfully reproduces the source design.
+
+---
+
+## Why this is necessary
+
+`get_design_context` returns a bag of component snippets, not a spatial layout description. It tells you "there's a Button with variant=primary" but not "there's a sidebar on the left with 3 nav groups and a divider between each." Common gaps:
+
+- **Sidebar navigation** — presence, structure, active states, section groupings
+- **Top navigation bar** — logo, nav items, space/environment pill, utility icons
+- **Filter patterns** — chips vs dropdowns, filter bar composition, "+ Add filter" buttons
+- **Table composition** — column count, avatar columns, icon prefixes on names, workflow badges
+- **Data formatting** — absolute dates vs relative, "by Author" attribution patterns
+- **Page chrome** — breadcrumbs, back buttons, action bar composition
+
+The model fills these gaps with "plausible defaults" from training data, producing a reasonable but inaccurate page. Visual verification catches this.
+
+---
+
+## The verification loop
+
+### Step 1: Screenshot the source design
+
+Before or immediately after generating code, capture the Figma source:
+
+```
+get_screenshot(fileKey, nodeId)
+```
+
+Study this screenshot. Before writing any code, inventory every visible element:
+
+- Is there a sidebar? What sections and items does it contain?
+- Is there a top nav? What items are in it?
+- How many table columns are there? What's in each?
+- What filter controls are visible? Chips, dropdowns, search?
+- Are there avatars, icons, or badges alongside content?
+
+### Step 2: Generate the code
+
+Write the React/Forma 36 code using the design context + Code Connect snippets + skill guidelines. Use the screenshot inventory from Step 1 to ensure you account for every element.
+
+### Step 3: Render and screenshot the output
+
+Start a local dev server (or use an existing one) and open the generated page:
+
+```
+# Start dev server if needed
+npm run dev
+
+# Navigate to the page
+browser_navigate("http://localhost:5173/your-page")
+
+# Wait for render
+browser_wait_for("networkidle")
+
+# Capture
+browser_take_screenshot()
+```
+
+### Step 4: Compare screenshots
+
+Place both screenshots side by side (the model sees both in context). Systematically check:
+
+| Check               | What to look for                                          |
+| ------------------- | --------------------------------------------------------- |
+| **Navigation**      | Same sidebar? Same top bar? Same nav items and groupings? |
+| **Layout**          | Same number of columns/sections? Sidebar width matches?   |
+| **Table columns**   | Same column count, headers, and content in each?          |
+| **Filters**         | Same filter controls in the same arrangement?             |
+| **Icons & avatars** | Entry icons, user avatars, status icons all present?      |
+| **Badges & status** | Same badge types, colors, and positions?                  |
+| **Actions**         | Same buttons in header? Same row action menus?            |
+| **Data format**     | Dates, attribution, counts formatted the same way?        |
+| **Typography**      | Same heading levels, font weights, text colors?           |
+| **Empty space**     | Any large gaps or missing sections?                       |
+
+For each difference found, note the specific element and what needs to change.
+
+### Step 5: Fix and re-verify
+
+Update the code to address every difference. Then re-render, re-screenshot, and compare again. Stop when no meaningful differences remain.
+
+---
+
+## Typical findings by category
+
+These are the most commonly missed elements, ordered by frequency:
+
+1. **Sidebar navigation** — most often completely missing when the design context is truncated
+2. **Top navigation bar** — logo, nav items, environment indicator
+3. **Table column mismatch** — missing avatar/icon columns, missing workflow/metadata columns
+4. **Filter chip bar** — replaced with dropdowns when the design uses filter chips
+5. **Content type icons** — small icons next to entry names in list views
+6. **Date formatting** — relative ("2 hours ago") when design shows absolute ("04 June 2024")
+7. **Author attribution** — "Created by" with avatar vs plain text
+
+---
+
+## When to skip verification
+
+- **Path A/B** (no Figma source) — there's no reference design to compare against
+- **Small component snippets** — if translating a single component, not a full page
+- **Iteration on a known-good base** — if you're making targeted edits to verified code

From 17fd2319e7019efeda54bcf4b6b929b8ff91c798 Mon Sep 17 00:00:00 2001
From: toniwowtscherk <toni.wowtscherk@contentful.com>
Date: Thu, 30 Apr 2026 10:01:15 +0200
Subject: [PATCH 11/13] docs: make base-shell design-driven, enforce Navbar
 component
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Restructure base-shell.md to be design-first: the source Figma frame is
the authority, and each structural element (navbar, sidebar, content area)
is conditional on whether the design includes it. Key changes:

- Every section gated with "when the design includes..."
- Mandate <Navbar> from @contentful/f36-navbar (never hand-build)
- Document box-sizing: border-box requirement (fixes 60→92px navbar)
- Enforce size="small" (32px) for all buttons
- Expanded common mistakes table with new anti-patterns

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 skills/guidelines/composition/base-shell.md | 253 +++++++++++++++++---
 1 file changed, 216 insertions(+), 37 deletions(-)

diff --git a/skills/guidelines/composition/base-shell.md b/skills/guidelines/composition/base-shell.md
index b93a4ce38c..1bc1269079 100644
--- a/skills/guidelines/composition/base-shell.md
+++ b/skills/guidelines/composition/base-shell.md
@@ -1,70 +1,249 @@
 # Base Shell
 
-Every Contentful screen uses this exact shell. Do not invent alternative chrome.
+The source Figma design is the single source of truth. This guide provides the correct Forma 36 implementation for each structural element — use the patterns below **when the design includes them**, but never add elements the design doesn't show.
+
+## Principle
+
+Replicate the source design 1:1. If the design omits the navbar, omit it. If it shows a different sidebar width, match it. If it uses a non-standard layout (full-bleed editor, modal, settings panel), build what you see — don't force it into the shell below.
+
+---
+
+## Structural elements
+
+Most Contentful screens follow this layout, but not all. Match the source.
 
 ```
 +---------------------------------------------------------+
-|  Top bar  (52px, gray-100 background)                   |
+|  Top bar  (60px, gray-100 background)                   |
 +----------------+----------------------------------------+
 |                |  Content area                           |
 |  Sidebar       |  +------------------------------------+|
-|  (240px)       |  |  Header (title + actions)          ||
+|  (280px)       |  |  Header (title + actions)          ||
 |                |  +------------------------------------+|
 |                |  |  Page content                      ||
 |                |  +------------------------------------+|
 +----------------+----------------------------------------+
-                                                [8px agent strip]
 ```
 
-## Top bar
+When all three elements are present, this is the structural skeleton:
+
+```tsx
+import { Navbar } from '@contentful/f36-navbar';
+
+<Box style={{ minHeight: '100vh', display: 'flex', flexDirection: 'column' }}>
+  {/* Top bar — only if the design shows it */}
+  <Navbar ... />
+
+  <Flex style={{ flex: 1 }}>
+    {/* Sidebar — only if the design shows it */}
+    <Box style={{ width: '280px', flexShrink: 0, ... }}>
+      ...
+    </Box>
+
+    {/* Content area — fills remaining width */}
+    <Box style={{ flex: 1, ... }}>
+      <Box style={{ padding: '12px 24px 0' }}>
+        ...
+      </Box>
+    </Box>
+  </Flex>
+</Box>
+```
+
+---
+
+## Top bar — `Navbar` component
+
+**When the design includes a top navigation bar**, use the `Navbar` component from `@contentful/f36-navbar`. Never hand-build it with Flex, Box, or custom styles.
+
+The Navbar has a fixed height of `60px`, renders the Contentful logo automatically, and handles responsive behavior, spacing, and active states.
+
+> **Requires a global `box-sizing: border-box` CSS reset.** The Navbar sets `height: 60px` with internal padding — without `border-box`, the browser adds padding on top of the height, inflating it to ~92px. Ensure your app includes:
+>
+> ```css
+> *,
+> *::before,
+> *::after {
+>   box-sizing: border-box;
+> }
+> ```
+
+```tsx
+import { Navbar } from '@contentful/f36-navbar';
+```
+
+### Navbar.Item — nav items with icons
+
+Each nav item **must** use `Navbar.Item` with the `icon` and `title` props. The component handles height (32px), padding, icon sizing, active state styling, and typography automatically.
+
+```tsx
+<Navbar.Item title="Content" icon={<ImageSquareIcon />} isActive />
+<Navbar.Item title="Media" icon={<GlobeIcon />} />
+```
+
+- **`isActive`** renders the blue active pill (background + border)
+- **`icon`** renders a 16px icon before the label — always provide one
+- **`title`** is the nav label text
+- **`as`** allows polymorphic rendering (e.g., `as="a"` for links)
+- Items with **children** render as dropdown menus automatically
+
+### Navbar.Switcher — environment pill
+
+```tsx
+<Navbar.Switcher
+  space="Space"
+  environment="Production"
+  envVariant="master" // "master" = green, "non-master" = orange, "trial" = blue
+  isAlias={false}
+/>
+```
+
+The switcher renders the green (or orange/blue) environment pill with correct colors, padding, and typography. Never hand-build this.
+
+### Navbar.Account — user avatar
+
+```tsx
+<Navbar.Account
+  username="Conny Contentful"
+  avatar="https://..." // optional image URL
+  initials="CC" // fallback when no avatar
+  label="Account settings"
+>
+  <Navbar.MenuItem title="Account settings" />
+  <Navbar.MenuDivider />
+  <Navbar.MenuItem title="Log out" />
+</Navbar.Account>
+```
 
-Height `52px`, background `gray100`. Horizontal padding: `24px` left, `64px` right (the 64px gap is reserved for the agent strip).
+### Complete Navbar example
+
+```tsx
+<Navbar
+  mainNavigation={
+    <>
+      <Navbar.Item title="Content model" icon={<PenNibIcon />} />
+      <Navbar.Item title="Content" icon={<ImageSquareIcon />} isActive />
+      <Navbar.Item title="Experiences" icon={<SparkleIcon />} />
+      <Navbar.Item title="Media" icon={<GlobeIcon />} />
+      <Navbar.Item title="AI & Automations" icon={<SparkleIcon />} />
+      <Navbar.Item title="Apps">
+        <Navbar.MenuItem title="Installed apps" />
+        <Navbar.MenuItem title="Marketplace" />
+      </Navbar.Item>
+    </>
+  }
+  switcher={
+    <Navbar.Switcher
+      space="Space"
+      environment="Production"
+      envVariant="master"
+    />
+  }
+  account={
+    <Navbar.Account username="User" initials="U" label="Account">
+      <Navbar.MenuItem title="Account settings" />
+      <Navbar.MenuDivider />
+      <Navbar.MenuItem title="Log out" />
+    </Navbar.Account>
+  }
+/>
+```
 
-**Left side:** Contentful "C" logo -> Space/Environment switcher pill
-**Right side:** Search icon -> Help icon -> User avatar (24px)
+### When the design shows a different top bar
 
-**Environment switcher:**
+Some Contentful screens use a simplified header, a breadcrumb bar, or no top bar at all. If the source design does not show the standard Navbar (logo + nav items + environment pill + account), do not add one. Build what the design shows using the appropriate Forma 36 components.
 
-- Background: `green100`
-- Border: `green400`
-- Text: `green700` — "Space > Production"
-- Right-edge indicator strip: `green300`
-- Icon: rocket
+---
 
 ## Sidebar
 
-Width `240px`, white background, `boxShadowDefault`, top corners rounded to `12px`.
-Padding: `pt-12px pb-8px px-4px`. Inner menu: `px-12px`, gap between sections `12px`.
+**When the design includes a sidebar**, use these specs:
+
+- **Width:** match the source design — the standard Contentful sidebar is `280px`, but some designs use narrower or wider sidebars. Default to `280px` if the exact width is ambiguous.
+- **`flexShrink: 0`** — never let it compress
+- **Background:** `tokens.colorWhite`
+- **Border radius:** `12px 0 0 0` (top-left only)
+- **Inner padding:** `24px top`, `8px bottom`, `12px` horizontal. Inner menu groups: `padding: 0 12px`, `gap: 12px` between sections.
+
+### Nav items
 
-Always implement the sidebar faithfully — replicate all sections, items, icons, and states exactly. Never stub or simplify it.
+Each item is `34px` tall (`32px` inner + `1px` top margin). Inner: `padding: 6px 12px`, `gap: 8px`, `border-radius: 4px`.
 
-**Nav item** (32px tall): `px-12px py-6px`, `gap-8px`, `border-radius: 4px`
+- **Icon:** 20x20px — use the appropriate Phosphor icon from `@contentful/f36-icons` or the icon-shim
+- **Label:** body text, `tokens.gray900`
+- **Active:** `tokens.blue100` background
+- **Default:** transparent
+- **Hover:** `tokens.gray100`
 
-- Icon (16px, duotone for active) + label (body, `gray900`) + optional caret
-- Active: `blue100` background
-- Default: transparent
-- Hover: `gray100` background
+### Sections (separated by `gray200` bottom border)
 
-**Sections** (separated by `gray200` bottom border):
+Section title: `font-size: 12px`, `font-weight: 600`, `color: tokens.gray700`, `height: 28px`, `padding-left: 16px`.
 
-1. **Setup** — Design System, Content Model
-2. **Creation** — Experiences, Content
-3. **Optimization** — Optimizations, Analytics
-4. **Platform Configuration** — Collections, AI & Automations, Taxonomy, Apps
-5. _(no title)_ — Settings
+Replicate the exact sections shown in the source design — do not add or remove sections.
 
-Section title: `12px` size, `600` weight, `gray700`, `28px` tall, `pl-12px`.
-Collapse button: transparent `IconButton` with `CaretLeft` icon, bottom-right of sidebar.
+### When the design has no sidebar
+
+Some pages (entry editors, settings, modals, full-bleed layouts) omit the sidebar entirely. If the source design doesn't show one, don't add one — let the content area fill the full width.
+
+---
 
 ## Content area
 
-Fills remaining width. White background, `boxShadowDefault`, top corners rounded to `12px`.
-Padding: `pt-12px px-24px`.
+**When the design includes a main content area** (nearly all pages):
+
+- **`flex: 1`** — fills all remaining width after sidebar (or full width if no sidebar)
+- **Background:** `tokens.colorWhite`
+- **Border radius:** `12px 12px 0 0` (both top corners) when adjacent to a sidebar; adjust if the layout differs
+- **Inner padding:** `12px` top, `24px` left and right, `0` bottom
+
+Do not use `tokens.spacingL` (which is 24px) for the top padding — use `12px`.
+
+### Header
 
-**Top:** `Header` component — always present, never omit.
+When the design shows a page header:
 
-- Use `Title` variant for top-level pages
-- Use `Breadcrumb` variant for subpages
-- Set `dividerLine={true}` when content area has a right sidebar
+- **Title variant** for top-level pages (e.g., "All content", "Content model")
+- **Breadcrumb variant** for subpages (e.g., entry editor, settings detail)
+
+The header area (title row + filter/search bar) sits inside the padded zone. The table or main content below it should be full-width (no horizontal padding) so table borders span edge to edge.
+
+### Tables
+
+When the page contains a table:
+
+- The table extends full-width within the content area (no horizontal padding on the table itself)
+- **Header row height:** `36px` — override the Forma 36 default if needed
+- **Body row height:** `56px`
+- Pad header/body text with `12px` horizontal cell padding
+
+---
+
+## Buttons
+
+Default button height in Contentful is `32px`. Use `size="small"` on the Forma 36 `Button` component. Do not let buttons render at the default `40px` height — that is the "medium" size and is too tall for most Contentful UI contexts.
+
+```tsx
+<Button variant="secondary" size="small">View</Button>
+<Button variant="positive" size="small" startIcon={<PlusIcon />}>Add entry</Button>
+```
 
-**Below header:** unrestricted content area.
+The only exception is if the source design explicitly shows a larger button (e.g., in a hero or empty state).
+
+---
+
+## Common mistakes
+
+| Mistake                                           | Correct approach                                   |
+| ------------------------------------------------- | -------------------------------------------------- |
+| Adding a navbar the design doesn't show           | Only include elements visible in the source design |
+| Hand-building the top bar with Flex/Box           | Use `<Navbar>` from `@contentful/f36-navbar`       |
+| Navbar items without icons                        | Always pass `icon` prop to `Navbar.Item`           |
+| Hand-building the environment switcher            | Use `<Navbar.Switcher>`                            |
+| Buttons at 40px height (medium)                   | Use `size="small"` for 32px buttons                |
+| Sidebar width guessed at 200px or 240px           | Default to `280px`, or match the source design     |
+| Content area top padding `spacingL` (24px)        | Use `12px`                                         |
+| Navbar at 92px instead of 60px                    | Ensure global `box-sizing: border-box` reset       |
+| Omitting the sidebar when the design shows one    | Always replicate every section shown in the source |
+| Adding a sidebar when the design doesn't show one | Only include elements visible in the source design |
+| Table header taller than 36px                     | Cap at `36px`                                      |
+| Inventing sidebar sections not in the design      | Replicate the source exactly                       |

From 6f687bf3f56ff40c2fd6e2798f3c297ee9fe99b7 Mon Sep 17 00:00:00 2001
From: toniwowtscherk <toni.wowtscherk@contentful.com>
Date: Thu, 30 Apr 2026 10:51:38 +0200
Subject: [PATCH 12/13] refactor(forma36): remove Paths D and E from skill
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Paths D (Code → Figma) and E (Edit existing Figma design) output Figma
Plugin API JavaScript, not React with Forma 36 components. They don't
belong in a design system skill — removed to keep the scope focused on
the three React-based workflows (A/B/C).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 skills/SKILL.md | 91 +------------------------------------------------
 1 file changed, 1 insertion(+), 90 deletions(-)

diff --git a/skills/SKILL.md b/skills/SKILL.md
index e2508c9f56..6839da2c9a 100644
--- a/skills/SKILL.md
+++ b/skills/SKILL.md
@@ -34,7 +34,7 @@ REQUIRED  Skeleton sub-components: Skeleton.Container, Skeleton.DisplayText, Ske
 
 ## Choose your path
 
-This skill serves five workflows. Pick the one that matches your task, then follow its reading order.
+This skill serves three workflows. Pick the one that matches your task, then follow its reading order.
 
 ### Path A — Designer prototyping (no Figma URL)
 
@@ -130,95 +130,6 @@ This loop typically converges in 1–2 iterations. The first comparison catches
 
 See `guidelines/composition/visual-verification.md` for the detailed checklist.
 
-### Path D — Code to Figma design (writing to Figma via MCP)
-
-You have existing code, a running prototype, or a component implementation and want to push it into a Figma file as a design. This uses the Figma MCP server's write capabilities.
-
-**Prerequisites:**
-
-- Figma MCP server connected (remote `mcp.figma.com` or local `127.0.0.1:3845/mcp`)
-- Load the `figma-use` skill **before every `use_figma` call** — mandatory, skipping it causes hard-to-debug failures
-- For full-page layouts, also load the `figma-generate-design` skill
-
-**How this works:**
-
-1. Read the source code to understand what components, tokens, and layout patterns are used
-2. Use `search_design_system` via MCP to discover matching Forma 36 Figma components, variables, and styles in the target file's libraries
-3. Map React props back to Figma component properties using `guidelines/code-connect.md` in reverse — e.g. `variant="primary"` on `<Button>` means set Figma property "Type" to "Primary"
-4. Build the design in Figma section-by-section using `use_figma`, importing library components rather than drawing raw shapes
-5. Bind Figma variables (color, spacing, typography) instead of hardcoding values — this keeps the design connected to the design system
-
-**Reading order:**
-
-1. Read the source code — identify all Forma 36 components, tokens, and screen pattern used
-2. `guidelines/code-connect.md` — Use the mapping table **in reverse** (React prop -> Figma property name) to set correct variant properties on Figma components
-3. `guidelines/tokens/color.md` + `guidelines/tokens/spacing.md` — Know which token values to bind as Figma variables
-4. `guidelines/composition/base-shell.md` — Replicate the app chrome faithfully in the Figma frame
-5. Load `figma-use` skill — required Plugin API reference for every `use_figma` call
-6. Load `figma-generate-design` skill — for multi-section page assembly workflow
-
-**Key principles:**
-
-- **Use library components, not raw shapes.** Call `search_design_system` to find the published Forma 36 component, then create an instance. Never recreate a Button from rectangles and text.
-- **Reverse the Code Connect table.** If the code says `<Button variant="primary" size="small">`, set Figma properties `Type=Primary`, `Size=Small (default)` on the component instance.
-- **Bind variables, don't hardcode.** Map `tokens.spacingM` to the corresponding Figma spacing variable, `tokens.blue600` to the color variable. This keeps the design token-connected.
-- **Build incrementally.** For full pages, assemble section-by-section — header first, then sidebar, then content area — verifying each section via `get_screenshot` before moving on.
-- **Match the real layout.** Use auto-layout in Figma to mirror the Flex/Stack/Grid structure in code. A `<Stack flexDirection="column" spacing="spacingM">` becomes a vertical auto-layout frame with `itemSpacing=16`.
-
-**When to use this path vs. `figma-capture-to-file`:**
-
-- Use **Path D** when you want an editable, token-connected, component-based Figma design that designers can iterate on
-- Use **`figma-capture-to-file`** when you just need a flat screenshot of a running localhost dropped into a Figma frame
-
-### Path E — Edit existing Figma design (modify a frame on canvas)
-
-A designer points to an existing Figma frame (via URL or desktop selection) and asks for changes — swap a variant, adjust layout, add a component, rearrange sections, update copy, or restyle an element. The design already exists; you are modifying it in place.
-
-**Prerequisites:**
-
-- Figma MCP server connected (remote `mcp.figma.com` or local `127.0.0.1:3845/mcp`)
-- Load the `figma-use` skill **before every `use_figma` call** — mandatory
-
-**How this works:**
-
-1. Fetch the current state of the frame using `get_design_context` or `get_screenshot` to understand what's already there
-2. Identify the specific nodes that need to change — use `get_metadata` or the Plugin API via `use_figma` to walk the layer tree
-3. Make targeted edits using `use_figma` — change properties, swap component instances, reorder children, update text, adjust auto-layout settings
-4. Verify each edit with `get_screenshot` before moving to the next change
-5. Use `guidelines/code-connect.md` to ensure any component property changes use correct Figma property names (e.g., set "Type" not "Variant")
-
-**Reading order:**
-
-1. Fetch the design — `get_design_context` or `get_screenshot` to see the current state
-2. `guidelines/code-connect.md` — Reference the Figma property names when changing component variants (the "Figma prop" column is what you set on the canvas)
-3. `guidelines/tokens/` — When changing colors, spacing, or typography, bind to Figma variables matching the token names
-4. `guidelines/composition/screen-patterns.md` — If restructuring a page, verify the result still follows the correct pattern
-5. `guidelines/foundations/writing.md` — If updating copy, follow the writing rules (sentence case, verb-first labels, "Never mind")
-6. Load `figma-use` skill — required before every `use_figma` call
-
-**Key principles:**
-
-- **Read, log, then write.** Always fetch current state AND return current property values before overwriting. Use a read-only `use_figma` call that returns `{ before: { componentProperties, text, fills } }`, then a separate write call. See `guidelines/code-connect.md` for the pattern.
-- **Edit surgically.** Change only what was requested. Don't reorganize layers, rename nodes, or "clean up" the design unless asked.
-- **Preserve component instances.** When swapping a variant, change the property on the existing instance — don't detach it and rebuild.
-- **Use Figma property names, not React names.** On the canvas, it's "Type" not "variant", "Small (default)" not "small". The Code Connect table's "Figma prop" column is your reference.
-- **Verify after EVERY edit.** Call `get_screenshot` MCP tool after each `use_figma` write. This is mandatory, not optional. Do not skip this step.
-- **Respect auto-layout.** If a frame uses auto-layout, work within it — add children, change spacing, adjust padding. Don't switch to absolute positioning unless the designer explicitly asks.
-
-**Common edit operations:**
-
-- Change a component variant: set the Figma property (e.g., `Type=Negative` on a Button instance)
-- Update text content: find the text node and set `characters`
-- Add a component: use `search_design_system` to find it, create instance, insert into the target frame
-- Reorder items: move child nodes within their parent's `children` array
-- Adjust spacing: change `itemSpacing` on an auto-layout frame, or `paddingTop`/`paddingBottom`/etc.
-- Swap an icon: find the icon instance, swap its component to a different one from the library
-
-**When to use Path E vs. Path D:**
-
-- Use **Path E** when a design already exists and needs modification
-- Use **Path D** when creating a new design from scratch based on code
-
 ---
 
 ## Critical rules

From 19c486ad3b838b4fe758dce9cfea70bae534d72b Mon Sep 17 00:00:00 2001
From: toniwowtscherk <toni.wowtscherk@contentful.com>
Date: Thu, 30 Apr 2026 16:02:08 +0200
Subject: [PATCH 13/13] =?UTF-8?q?docs(skill):=20V5-V9=20fixes=20=E2=80=94?=
 =?UTF-8?q?=20CSS=20import=20removal,=20button=20size,=20icon=20correction?=
 =?UTF-8?q?s,=20token=20compliance?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Syncs all skill improvements from V5 through V9:
- Remove nonexistent `dist/styles.css` import (f36 v6 uses Emotion)
- Standardize all examples to `style` prop over Emotion `css` prop
- Add `size="small"` to every Button/IconButton (32px standard, never 40px)
- Fix 38 wrong icon names to Phosphor convention
- Fix shadow token names, add HouseIcon, correct CloseCircleIcon → WarningOctagonIcon
- Replace hardcoded padding with f36 tokens, add token compliance exceptions
- Add app-shell.tsx example with Navbar, sidebar, and content area
- Rename confirmation-dialog → confirmation-modal

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 skills/SKILL.md                               |  42 ++--
 skills/examples/app-shell.tsx                 | 225 ++++++++++++++++++
 skills/examples/confirmation-modal.tsx        |  11 +-
 skills/examples/detail-page.tsx               |  10 +-
 skills/examples/error-state.tsx               |  18 +-
 skills/examples/form-page.tsx                 |   8 +-
 skills/examples/list-page.tsx                 |   6 +-
 skills/examples/settings-page.tsx             |  12 +-
 skills/guidelines/composition/base-shell.md   |   5 +-
 .../guidelines/composition/screen-patterns.md |   2 +-
 skills/guidelines/foundations/icons.md        |   3 +-
 skills/guidelines/setup.md                    |  10 +-
 12 files changed, 295 insertions(+), 57 deletions(-)
 create mode 100644 skills/examples/app-shell.tsx

diff --git a/skills/SKILL.md b/skills/SKILL.md
index 6839da2c9a..687e28ec06 100644
--- a/skills/SKILL.md
+++ b/skills/SKILL.md
@@ -22,12 +22,12 @@ Forma 36 is the design language of Contentful. Every screen, component, and inte
 ## Pre-flight checklist — VERIFY before generating ANY code
 
 ```
-REQUIRED  import '@contentful/f36-components/dist/styles.css'  — without this, all components render unstyled
+REQUIRED  f36 v6 is self-styling via Emotion — NO CSS import needed. Do NOT add `import '@contentful/f36-components/dist/styles.css'` — that file does not exist and will break the build.
 REQUIRED  Every component has an explicit import from @contentful/f36-components or @contentful/f36-icons
-REQUIRED  All icon names come from @contentful/f36-icons (Phosphor set) — see guidelines/foundations/icons.md for the approved list. NEVER invent icon names. Common: DotsThreeIcon (menus), TrashIcon (delete), PencilIcon (edit), GearIcon (settings), PlusIcon, SearchIcon, CloseIcon, CheckIcon, WarningIcon, ArrowLeftIcon.
+REQUIRED  All icon names come from @contentful/f36-icons (Phosphor set) — see guidelines/foundations/icons.md for the approved list. NEVER invent icon names. Common: DotsThreeIcon (menus), TrashSimpleIcon (delete), PencilSimpleIcon (edit), GearSixIcon (settings), PlusIcon, MagnifyingGlassIcon (search), XIcon (close), CheckIcon, WarningIcon, ArrowLeftIcon.
 REQUIRED  All colors, spacing, typography use @contentful/f36-tokens — NEVER hardcode hex, px, or font stacks
 REQUIRED  Use Layout (not Workbench) as the page shell. Layout.Header, Layout.Body, Layout.Sidebar are REAL compound sub-components (verified in source) — use them confidently. These are the ONLY valid sub-components.
-REQUIRED  Skeleton sub-components: Skeleton.Container, Skeleton.DisplayText, Skeleton.BodyText, Skeleton.Image — these are the ONLY valid sub-components. There is NO Skeleton.Row.
+REQUIRED  Skeleton sub-components: Skeleton.Container, Skeleton.DisplayText, Skeleton.BodyText, Skeleton.Image, Skeleton.Row — these are the ONLY valid sub-components. Use Skeleton.Row inside Table.Body for table loading states (props: rowCount, columnCount).
 ```
 
 ---
@@ -136,7 +136,7 @@ See `guidelines/composition/visual-verification.md` for the detailed checklist.
 
 These apply to all paths. Do not override them.
 
-- **CSS import is REQUIRED** — every file must include `import '@contentful/f36-components/dist/styles.css';`. Without it, all components render unstyled. This is the #1 most-forgotten rule.
+- **No CSS import needed** — f36 v6 uses Emotion for runtime styling. `@contentful/f36-components/dist/styles.css` does not exist. Do NOT add it — it will cause a build error.
 - **Tokens only** — never hardcode hex colors, pixel values, or font stacks. Always use `@contentful/f36-tokens`.
 - **Sentence case** — all labels, headings, buttons, menu items. Never Title Case or ALL CAPS.
 - **One primary button** per screen section maximum.
@@ -148,6 +148,7 @@ These apply to all paths. Do not override them.
 - **`Layout` not `Workbench`** — Workbench is deprecated.
 - **No custom shadows** — only `shadowDefault`, `shadowHeavy`, `shadowButton`, `insetBoxShadowDefault`.
 - **No border radius outside the scale** — 4px, 6px, 12px, 100px only.
+- **`Button size="small"` always** — the default 32px height is standard. Never use medium (40px).
 
 ---
 
@@ -161,6 +162,7 @@ From the [Forma 36 code style guide](https://github.com/contentful/forma-36/blob
 - Component type names use `ComponentNameProps` pattern
 - Use `camelCase` for all prop names
 - Pass string prop values with double quotes directly, not wrapped in `{}`
+- Use `style` prop for inline styles — it works universally. The `css` prop (Emotion) only works if the host app has Emotion configured (f36 uses it internally but doesn't expose it to consumers).
 - Prefer `className` over inline `style` unless manipulating dynamic values
 
 ---
@@ -168,14 +170,10 @@ From the [Forma 36 code style guide](https://github.com/contentful/forma-36/blob
 ## Dependencies
 
 ```bash
-npm install @contentful/f36-components @contentful/f36-tokens @contentful/f36-icons
+npm install @contentful/f36-components @contentful/f36-tokens @contentful/f36-icons @contentful/f36-navbar
 ```
 
-Requires React 18. Compatible with Vite. CSS import is mandatory:
-
-```tsx
-import '@contentful/f36-components/dist/styles.css';
-```
+Requires React 18. Compatible with Vite. f36 v6 is self-styling via Emotion — no CSS file import needed.
 
 Font: Geist from `https://cdn.f36.contentful.com`. Apply `font-feature-settings: 'ss05' 1`.
 
@@ -254,27 +252,29 @@ Each folder contains an `overview.md` that indexes its contents.
 
 Working TSX files demonstrating correct usage. Each maps to a screen pattern.
 
-| File                      | Pattern         | What it shows                                                                        |
-| ------------------------- | --------------- | ------------------------------------------------------------------------------------ |
-| `list-page.tsx`           | List / Index    | Table, search, EntityStatusBadge, Menu actions, Pagination, empty state, Skeleton    |
-| `detail-page.tsx`         | Detail / Edit   | Right sidebar, breadcrumbs, form validation, unsaved-changes Note                    |
-| `settings-page.tsx`       | Settings        | Grouped sections, Switch toggles, danger zone                                        |
-| `confirmation-dialog.tsx` | Confirmation    | Modal, "Never mind" cancel, `isLoading` confirm, `shouldCloseOnOverlayClick={false}` |
-| `form-page.tsx`           | Standalone Form | `Layout variant="narrow"`, grouped FormControls, Accordion, Notification             |
-| `error-state.tsx`         | Error State     | Centered error, WarningOctagonIcon, "Try again" + "Go back"                          |
+| File                      | Pattern         | What it shows                                                                                                          |
+| ------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `app-shell.tsx`           | Full app chrome | Navbar (from f36-navbar), sidebar (280px, nav items, sections), content area — the outer wrapper most pages sit inside |
+| `list-page.tsx`           | List / Index    | Table, search, EntityStatusBadge, Menu actions, Pagination, empty state, Skeleton                                      |
+| `detail-page.tsx`         | Detail / Edit   | Right sidebar, breadcrumbs, form validation, unsaved-changes Note                                                      |
+| `settings-page.tsx`       | Settings        | Grouped sections, Switch toggles, danger zone                                                                          |
+| `confirmation-dialog.tsx` | Confirmation    | Modal, "Never mind" cancel, `isLoading` confirm, `shouldCloseOnOverlayClick={false}`                                   |
+| `form-page.tsx`           | Standalone Form | `Layout variant="narrow"`, grouped FormControls, Accordion, Notification                                               |
+| `error-state.tsx`         | Error State     | Centered error, WarningOctagonIcon, "Try again" + "Go back"                                                            |
 
 ---
 
 ## Post-flight checklist — VERIFY before returning code to the user
 
 ```
-CHECK  CSS import present: import '@contentful/f36-components/dist/styles.css'
-CHECK  Every color, spacing, and font value comes from @contentful/f36-tokens — no hardcoded hex, px, or font stacks
+CHECK  No CSS import — f36 v6 is self-styling via Emotion. `dist/styles.css` does not exist and will break the build if imported.
+CHECK  Every color, spacing, and font value comes from @contentful/f36-tokens — no hardcoded hex, px, or font stacks (exception: shell structure dimensions like sidebar width, border-radius, and nav item padding that have no token equivalent — see base-shell.md)
 CHECK  Every icon name exists in @contentful/f36-icons — see guidelines/foundations/icons.md. If unsure, DON'T guess.
 CHECK  Every input is inside a FormControl with a Label
 CHECK  Only ONE primary button per visible screen section
 CHECK  All labels and headings use sentence case — never Title Case or ALL CAPS
 CHECK  Destructive confirmation cancel label is "Never mind" — not "Cancel"
 CHECK  No usage of Workbench — use Layout instead
-CHECK  No fabricated sub-components: Layout only has Layout.Header, Layout.Body, Layout.Sidebar. Skeleton only has Skeleton.Container, Skeleton.DisplayText, Skeleton.BodyText, Skeleton.Image.
+CHECK  No fabricated sub-components: Layout only has Layout.Header, Layout.Body, Layout.Sidebar. Skeleton only has Skeleton.Container, Skeleton.DisplayText, Skeleton.BodyText, Skeleton.Image, Skeleton.Row.
+CHECK  Every Button and IconButton uses size="small" — never omit (defaults to medium/40px).
 ```
diff --git a/skills/examples/app-shell.tsx b/skills/examples/app-shell.tsx
new file mode 100644
index 0000000000..8fc7c5f09e
--- /dev/null
+++ b/skills/examples/app-shell.tsx
@@ -0,0 +1,225 @@
+import {
+  Box,
+  Flex,
+  Header,
+  Button,
+  Table,
+  TextInput,
+  EntityStatusBadge,
+  Menu,
+  IconButton,
+  Pagination,
+  Text,
+} from '@contentful/f36-components';
+// Navbar is a separate package — not in f36-components
+import { Navbar } from '@contentful/f36-navbar';
+import {
+  PlusIcon,
+  MagnifyingGlassIcon,
+  DotsThreeIcon,
+  PenNibIcon,
+  ImageSquareIcon,
+  SparkleIcon,
+  GlobeIcon,
+  GearSixIcon,
+  TreeStructureIcon,
+  TagIcon,
+} from '@contentful/f36-icons';
+import tokens from '@contentful/f36-tokens';
+
+// Full app shell: Navbar (60px) + sidebar (280px) + content area
+// Only include structural elements the design shows — see base-shell.md
+function AppShellExample() {
+  return (
+    <Box
+      style={{ minHeight: '100vh', display: 'flex', flexDirection: 'column' }}
+    >
+      {/* Navbar from @contentful/f36-navbar — never hand-build with Flex/Box */}
+      {/* Requires global box-sizing: border-box or it renders 92px instead of 60px */}
+      <Navbar
+        mainNavigation={
+          <>
+            <Navbar.Item title="Content model" icon={<PenNibIcon />} />
+            <Navbar.Item title="Content" icon={<ImageSquareIcon />} isActive />
+            <Navbar.Item title="Experiences" icon={<SparkleIcon />} />
+            <Navbar.Item title="Media" icon={<GlobeIcon />} />
+            <Navbar.Item title="Apps">
+              <Navbar.MenuItem title="Installed apps" />
+              <Navbar.MenuItem title="Marketplace" />
+            </Navbar.Item>
+          </>
+        }
+        switcher={
+          <Navbar.Switcher
+            space="Acme Corp"
+            environment="Production"
+            envVariant="master"
+          />
+        }
+        account={
+          <Navbar.Account
+            username="Conny Contentful"
+            initials="CC"
+            label="Account"
+          >
+            <Navbar.MenuItem title="Account settings" />
+            <Navbar.MenuDivider />
+            <Navbar.MenuItem title="Log out" />
+          </Navbar.Account>
+        }
+      />
+
+      <Flex style={{ flex: 1 }}>
+        {/* Sidebar: 280px default, flexShrink: 0, top-left border-radius 12px */}
+        <Box
+          style={{
+            width: '280px',
+            flexShrink: 0,
+            backgroundColor: tokens.colorWhite,
+            borderRadius: '12px 0 0 0',
+            padding: '24px 12px 8px',
+          }}
+        >
+          {/* Section title: 12px, weight 600, gray700 */}
+          <Text
+            style={{
+              fontSize: tokens.fontSizeS,
+              fontWeight: tokens.fontWeightDemiBold,
+              color: tokens.gray700,
+              display: 'block',
+              height: '28px',
+              paddingLeft: tokens.spacingM,
+            }}
+          >
+            Content
+          </Text>
+
+          <Flex flexDirection="column" style={{ gap: tokens.spacing2Xs }}>
+            {/* Active nav item: blue100 background, 34px tall, 4px radius */}
+            <Flex
+              alignItems="center"
+              style={{
+                height: '34px',
+                padding: `${tokens.spacing2Xs} ${tokens.spacingS}`,
+                gap: tokens.spacingXs,
+                borderRadius: tokens.borderRadiusSmall,
+                backgroundColor: tokens.blue100,
+                cursor: 'pointer',
+              }}
+            >
+              <ImageSquareIcon size="small" />
+              <Text style={{ color: tokens.gray900 }}>Entries</Text>
+            </Flex>
+
+            <Flex
+              alignItems="center"
+              style={{
+                height: '34px',
+                padding: `${tokens.spacing2Xs} ${tokens.spacingS}`,
+                gap: tokens.spacingXs,
+                borderRadius: tokens.borderRadiusSmall,
+                cursor: 'pointer',
+              }}
+            >
+              <TreeStructureIcon size="small" />
+              <Text style={{ color: tokens.gray900 }}>Content types</Text>
+            </Flex>
+
+            <Flex
+              alignItems="center"
+              style={{
+                height: '34px',
+                padding: `${tokens.spacing2Xs} ${tokens.spacingS}`,
+                gap: tokens.spacingXs,
+                borderRadius: tokens.borderRadiusSmall,
+                cursor: 'pointer',
+              }}
+            >
+              <TagIcon size="small" />
+              <Text style={{ color: tokens.gray900 }}>Tags</Text>
+            </Flex>
+          </Flex>
+        </Box>
+
+        {/* Content area: flex 1, 12px top padding, 24px horizontal */}
+        <Box
+          style={{
+            flex: 1,
+            backgroundColor: tokens.colorWhite,
+            borderRadius: '12px 12px 0 0',
+            padding: `${tokens.spacingS} ${tokens.spacingL} 0`,
+          }}
+        >
+          {/* Header with title + primary action */}
+          <Header
+            title="Entries"
+            actions={
+              <Button variant="primary" size="small" startIcon={<PlusIcon />}>
+                Add entry
+              </Button>
+            }
+            filters={
+              <TextInput
+                type="search"
+                placeholder="Search entries"
+                icon={<MagnifyingGlassIcon />}
+              />
+            }
+          />
+
+          {/* Table: full width, no horizontal padding, 36px header rows, 56px body rows */}
+          <Table>
+            <Table.Head>
+              <Table.Row>
+                <Table.Cell>Name</Table.Cell>
+                <Table.Cell>Content type</Table.Cell>
+                <Table.Cell>Updated</Table.Cell>
+                <Table.Cell>Status</Table.Cell>
+                <Table.Cell width="60px" />
+              </Table.Row>
+            </Table.Head>
+            <Table.Body>
+              <Table.Row>
+                <Table.Cell>Homepage banner</Table.Cell>
+                <Table.Cell>Banner</Table.Cell>
+                <Table.Cell>2 hours ago</Table.Cell>
+                <Table.Cell>
+                  <EntityStatusBadge entityStatus="published" />
+                </Table.Cell>
+                <Table.Cell>
+                  <Menu>
+                    <Menu.Trigger>
+                      <IconButton
+                        icon={<DotsThreeIcon />}
+                        aria-label="Actions"
+                        variant="transparent"
+                        size="small"
+                      />
+                    </Menu.Trigger>
+                    <Menu.List>
+                      <Menu.Item>Edit</Menu.Item>
+                      <Menu.Item>Duplicate</Menu.Item>
+                      <Menu.Divider />
+                      <Menu.Item>Delete</Menu.Item>
+                    </Menu.List>
+                  </Menu>
+                </Table.Cell>
+              </Table.Row>
+            </Table.Body>
+          </Table>
+
+          <Flex justifyContent="center" marginTop="spacingL">
+            <Pagination
+              activePage={1}
+              onPageChange={() => {}}
+              totalItems={50}
+              itemsPerPage={20}
+            />
+          </Flex>
+        </Box>
+      </Flex>
+    </Box>
+  );
+}
+
+export { AppShellExample };
diff --git a/skills/examples/confirmation-modal.tsx b/skills/examples/confirmation-modal.tsx
index 5f54c1a24a..335df399ce 100644
--- a/skills/examples/confirmation-modal.tsx
+++ b/skills/examples/confirmation-modal.tsx
@@ -1,5 +1,3 @@
-// REQUIRED: CSS import — without this, all components render unstyled
-import '@contentful/f36-components/dist/styles.css';
 import { Modal, Button, Paragraph } from '@contentful/f36-components';
 import { useState } from 'react';
 
@@ -16,7 +14,7 @@ function DeleteContentTypeModal() {
 
   return (
     <>
-      <Button variant="negative" onClick={() => setIsOpen(true)}>
+      <Button variant="negative" size="small" onClick={() => setIsOpen(true)}>
         Delete content type
       </Button>
 
@@ -38,11 +36,16 @@ function DeleteContentTypeModal() {
         </Modal.Content>
         <Modal.Controls>
           {/* Cancel label MUST be "Never mind" for destructive confirmations — never "Cancel" */}
-          <Button variant="secondary" onClick={() => setIsOpen(false)}>
+          <Button
+            variant="secondary"
+            size="small"
+            onClick={() => setIsOpen(false)}
+          >
             Never mind
           </Button>
           <Button
             variant="negative"
+            size="small"
             isLoading={isDeleting}
             onClick={handleDelete}
           >
diff --git a/skills/examples/detail-page.tsx b/skills/examples/detail-page.tsx
index 8fb9267f84..d3744f6719 100644
--- a/skills/examples/detail-page.tsx
+++ b/skills/examples/detail-page.tsx
@@ -1,5 +1,3 @@
-// REQUIRED: CSS import — without this, all components render unstyled
-import '@contentful/f36-components/dist/styles.css';
 import {
   Layout,
   Header,
@@ -28,8 +26,12 @@ function EntryDetailPage() {
             dividerLine
             actions={
               <Stack spacing="spacingS">
-                <Button variant="secondary">Save</Button>
-                <Button variant="positive">Publish</Button>
+                <Button variant="secondary" size="small">
+                  Save
+                </Button>
+                <Button variant="positive" size="small">
+                  Publish
+                </Button>
               </Stack>
             }
           />
diff --git a/skills/examples/error-state.tsx b/skills/examples/error-state.tsx
index 56589e84c4..6e9dff01d6 100644
--- a/skills/examples/error-state.tsx
+++ b/skills/examples/error-state.tsx
@@ -1,5 +1,3 @@
-// REQUIRED: CSS import — without this, all components render unstyled
-import '@contentful/f36-components/dist/styles.css';
 import {
   Flex,
   Heading,
@@ -17,11 +15,11 @@ function PageError({ section = 'content types' }: { section?: string }) {
       alignItems="center"
       justifyContent="center"
       padding="spacing2Xl"
-      css={{ minHeight: '400px' }}
+      style={{ minHeight: '400px' }}
     >
       <WarningOctagonIcon
         size="medium"
-        css={{
+        style={{
           width: '48px',
           height: '48px',
           color: tokens.red600,
@@ -34,10 +32,18 @@ function PageError({ section = 'content types' }: { section?: string }) {
         try again.
       </Paragraph>
       <Stack spacing="spacingS">
-        <Button variant="primary" onClick={() => window.location.reload()}>
+        <Button
+          variant="primary"
+          size="small"
+          onClick={() => window.location.reload()}
+        >
           Try again
         </Button>
-        <Button variant="secondary" onClick={() => window.history.back()}>
+        <Button
+          variant="secondary"
+          size="small"
+          onClick={() => window.history.back()}
+        >
           Go back
         </Button>
       </Stack>
diff --git a/skills/examples/form-page.tsx b/skills/examples/form-page.tsx
index b4ce4ddbfd..acce2dadc0 100644
--- a/skills/examples/form-page.tsx
+++ b/skills/examples/form-page.tsx
@@ -1,5 +1,3 @@
-// REQUIRED: CSS import — without this, all components render unstyled
-import '@contentful/f36-components/dist/styles.css';
 import {
   Layout,
   Header,
@@ -32,8 +30,10 @@ function CreateContentTypePage() {
             withBackButton
             actions={
               <Stack spacing="spacingS">
-                <Button variant="secondary">Never mind</Button>
-                <Button variant="primary" onClick={handleSave}>
+                <Button variant="secondary" size="small">
+                  Never mind
+                </Button>
+                <Button variant="primary" size="small" onClick={handleSave}>
                   Create
                 </Button>
               </Stack>
diff --git a/skills/examples/list-page.tsx b/skills/examples/list-page.tsx
index 0c441b0d9b..18db51507e 100644
--- a/skills/examples/list-page.tsx
+++ b/skills/examples/list-page.tsx
@@ -1,5 +1,3 @@
-// REQUIRED: CSS import — without this, all components render unstyled
-import '@contentful/f36-components/dist/styles.css';
 import {
   Layout,
   Header,
@@ -33,7 +31,7 @@ function ContentTypesListPage() {
           <Header
             title="Content types"
             actions={
-              <Button variant="primary" startIcon={<PlusIcon />}>
+              <Button variant="primary" size="small" startIcon={<PlusIcon />}>
                 Add content type
               </Button>
             }
@@ -117,7 +115,7 @@ function ContentTypesEmptyState() {
         Content types define the structure of your content. Start by adding your
         first one.
       </Paragraph>
-      <Button variant="primary" startIcon={<PlusIcon />}>
+      <Button variant="primary" size="small" startIcon={<PlusIcon />}>
         Add content type
       </Button>
     </Flex>
diff --git a/skills/examples/settings-page.tsx b/skills/examples/settings-page.tsx
index de0eac4acd..cb44e52720 100644
--- a/skills/examples/settings-page.tsx
+++ b/skills/examples/settings-page.tsx
@@ -1,5 +1,3 @@
-// REQUIRED: CSS import — without this, all components render unstyled
-import '@contentful/f36-components/dist/styles.css';
 import {
   Layout,
   Header,
@@ -24,7 +22,11 @@ function WebhookSettingsPage() {
         <Layout.Header>
           <Header
             title="Webhook settings"
-            actions={<Button variant="primary">Save changes</Button>}
+            actions={
+              <Button variant="primary" size="small">
+                Save changes
+              </Button>
+            }
           />
         </Layout.Header>
       }
@@ -84,7 +86,9 @@ function WebhookSettingsPage() {
             >
               Deleting this webhook is permanent and cannot be undone.
             </Note>
-            <Button variant="negative">Delete webhook</Button>
+            <Button variant="negative" size="small">
+              Delete webhook
+            </Button>
           </Box>
         </Stack>
       </Layout.Body>
diff --git a/skills/guidelines/composition/base-shell.md b/skills/guidelines/composition/base-shell.md
index 1bc1269079..731709b1f6 100644
--- a/skills/guidelines/composition/base-shell.md
+++ b/skills/guidelines/composition/base-shell.md
@@ -29,6 +29,7 @@ When all three elements are present, this is the structural skeleton:
 
 ```tsx
 import { Navbar } from '@contentful/f36-navbar';
+import tokens from '@contentful/f36-tokens';
 
 <Box style={{ minHeight: '100vh', display: 'flex', flexDirection: 'column' }}>
   {/* Top bar — only if the design shows it */}
@@ -42,7 +43,7 @@ import { Navbar } from '@contentful/f36-navbar';
 
     {/* Content area — fills remaining width */}
     <Box style={{ flex: 1, ... }}>
-      <Box style={{ padding: '12px 24px 0' }}>
+      <Box style={{ padding: `${tokens.spacingS} ${tokens.spacingL} 0` }}>
         ...
       </Box>
     </Box>
@@ -50,6 +51,8 @@ import { Navbar } from '@contentful/f36-navbar';
 </Box>
 ```
 
+> **Token compliance note:** Shell structure dimensions like sidebar width (`280px`), nav item height (`34px`), and border-radius (`12px`) have no dedicated token — use raw pixel values for these. All other values (colors, spacing, typography) must use `@contentful/f36-tokens`.
+
 ---
 
 ## Top bar — `Navbar` component
diff --git a/skills/guidelines/composition/screen-patterns.md b/skills/guidelines/composition/screen-patterns.md
index 320b04e605..4fa317280a 100644
--- a/skills/guidelines/composition/screen-patterns.md
+++ b/skills/guidelines/composition/screen-patterns.md
@@ -124,7 +124,7 @@ Never show empty state while data is loading — show Skeleton.
 
 ```
 Centered container
-  |- Icon: WarningIcon or CloseCircleIcon, 48px, red600
+  |- Icon: WarningOctagonIcon, 48px, red600
   |- Heading: "Couldn't load [section]"
   |- Body: brief explanation + what user can do
   |- Actions: "Try again" (primary) + optional "Go back" (secondary)
diff --git a/skills/guidelines/foundations/icons.md b/skills/guidelines/foundations/icons.md
index 54ff453e35..8a632c259b 100644
--- a/skills/guidelines/foundations/icons.md
+++ b/skills/guidelines/foundations/icons.md
@@ -69,7 +69,7 @@ These are the most commonly used icons in `@contentful/f36-icons`. **Only use na
 
 ### UI & System
 
-`GearSixIcon` `DotsThreeIcon` `DotsThreeVerticalIcon` `DotsSixVerticalIcon` `GridFourIcon` `ColumnsIcon` `RowsIcon` `StarIcon` `HeartStraightIcon` `BookmarkSimpleIcon` `GlobeIcon` `GlobeXIcon` `UserIcon` `UsersIcon` `UsersThreeIcon` `LightningIcon` `RocketIcon` `RocketLaunchIcon` `LightbulbIcon` `FlaskIcon` `DiamondIcon` `CubeIcon` `TreeStructureIcon` `StackIcon` `WrenchIcon` `GaugeIcon`
+`GearSixIcon` `DotsThreeIcon` `DotsThreeVerticalIcon` `DotsSixVerticalIcon` `GridFourIcon` `ColumnsIcon` `RowsIcon` `StarIcon` `HeartStraightIcon` `BookmarkSimpleIcon` `GlobeIcon` `GlobeXIcon` `HouseIcon` `UserIcon` `UsersIcon` `UsersThreeIcon` `LightningIcon` `RocketIcon` `RocketLaunchIcon` `LightbulbIcon` `FlaskIcon` `DiamondIcon` `CubeIcon` `TreeStructureIcon` `StackIcon` `WrenchIcon` `GaugeIcon`
 
 ### Content modeling & Contentful-specific (custom icons)
 
@@ -104,3 +104,4 @@ These are the most commonly used icons in `@contentful/f36-icons`. **Only use na
 - ~~`HeartIcon`~~ → use `HeartStraightIcon`
 - ~~`EyeSlashIcon`~~ → use `EyeClosedIcon`
 - ~~`ExternalLinkIcon`~~ → use `ArrowSquareOutIcon`
+- ~~`HomeIcon`~~ → use `HouseIcon`
diff --git a/skills/guidelines/setup.md b/skills/guidelines/setup.md
index 5e675c63ae..a591e611d8 100644
--- a/skills/guidelines/setup.md
+++ b/skills/guidelines/setup.md
@@ -5,20 +5,16 @@
 Install the Forma 36 packages:
 
 ```bash
-npm install @contentful/f36-components @contentful/f36-tokens @contentful/f36-icons
+npm install @contentful/f36-components @contentful/f36-tokens @contentful/f36-icons @contentful/f36-navbar
 ```
 
 Forma 36 requires React 18 and is compatible with Vite.
 
 ## CSS
 
-Import the Forma 36 stylesheet at the root of your application:
+Forma 36 v6 uses **Emotion** for runtime CSS injection. Components are self-styling — there is no separate CSS file to import.
 
-```tsx
-import '@contentful/f36-components/dist/styles.css';
-```
-
-This import is required. Components will render without styles if you skip it.
+**Do NOT add** `import '@contentful/f36-components/dist/styles.css'` — this file does not exist in v6 and will cause a build error.
 
 ## Font