Restructure Forma 36 skill into granular guidelines format by toniwowtscherk · Pull Request #3385 · contentful/forma-36

toniwowtscherk · 2026-04-17T07:57:11Z

Summary

Restructures the Forma 36 skill from a monolithic format into a granular guidelines directory, adds 7 TSX reference implementations, and incorporates eval-driven improvements from V1–V9 iterations (average skill delta: +0.6 → +4.6).

Structure

skills/
├── SKILL.md                          # Entry point with 3-path routing (A: designer, B: developer, C: Figma-to-code)
├── guidelines/
│   ├── overview.md                   # Design philosophy, critical rules
│   ├── setup.md                      # Dependencies, fonts, tokens
│   ├── code-connect.md               # 48 components + 239 icons — Figma property → React prop mapping
│   ├── tokens/                       # color, typography, spacing, effects
│   ├── components/                   # layout, buttons, forms, feedback, navigation, data-display, content-media, utility
│   ├── composition/                  # base shell, 9 screen patterns, visual verification
│   └── foundations/                  # writing, icons, accessibility
└── examples/                         # app-shell, list-page, detail-page, settings-page, form-page, confirmation-dialog, error-state

What changed from the initial skill files

Granular format: Replaced monolithic SKILL.md + tokens.md + screen-patterns.md with ~30 focused files organized by topic
3-path routing: SKILL.md routes to different reading orders based on the task — designer prototyping (Path A), developer implementing (Path B), Figma-to-code translation (Path C)
7 TSX examples: Working reference implementations covering list, detail, settings, form, confirmation, error, and app shell patterns
Code Connect mappings: Complete table of 48 connected components and 239 icons with verified Figma property names
Eval-driven guardrails: Pre/post-flight checklists, closed Phosphor icon set, fixed fabricated APIs, inline rule comments in examples
Visual verification loop: Path C includes screenshot comparison workflow for Figma-to-code fidelity
Design-driven base shell: Figma source frame is the authority — navbar, sidebar, breadcrumbs are conditional on the design
V5–V9 fixes: Removed non-existent dist/styles.css import, standardized style prop, enforced Button size="small" (32px), fixed icon names, replaced hardcoded values with f36 tokens

Key rules enforced

No CSS import — f36 v6 is self-styling via Emotion
All values from @contentful/f36-tokens — no hardcoded hex, px, or font stacks
Phosphor icons only — closed set in icons.md, never invent names
Button size="small" always — 32px standard, never medium (40px)
Layout not Workbench — Workbench is deprecated
Sentence case everywhere — never Title Case or ALL CAPS
"Never mind" as cancel label for destructive confirmations

Test plan

All 7 TSX examples render without errors (Vite + React + f36 v6)
V9 skill eval: zero regressions across all 5 paths
Verify all internal file references in SKILL.md and overview.md point to existing files
Spot-check component prop tables against f36 v6 source
Confirm icon names in icons.md match @contentful/f36-icons exports

🤖 Generated with Claude Code

Add Forma 36 skill documentation for UI development using Contentful's design system, including rules, guidelines, and component usage.

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.

Add description for Forma 36 UI design system.

Updated the title to reflect 'Screen Patterns' instead of 'UI Patterns'.

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>

changeset-bot · 2026-04-17T07:57:16Z

⚠️ No Changeset found

Latest commit: 19c486a

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

vercel · 2026-04-17T07:57:17Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
forma-36	Ready	Preview	Apr 30, 2026 2:10pm
forma-36-storybook	Ready	Preview	Apr 30, 2026 2:10pm

github-actions · 2026-04-17T08:01:18Z

size-limit report 📦

Path	Size	Loading time (3g)	Running time (snapdragon)	Total time
CommonJS	132 KB (0%)	2.7 s (0%)	30 ms (+18.39% 🔺)	2.7 s
Module	128.99 KB (0%)	2.6 s (0%)	23 ms (-9.53% 🔽)	2.7 s

Kathrin Holzmann (Lelith) · 2026-04-23T12:48:44Z

+      alignItems="center"
+      justifyContent="center"
+      padding="spacing2Xl"
+      style={{ minHeight: '400px' }}


we should avoid this type of inline styles and write emotion style classes instead

Kathrin Holzmann (Lelith) · 2026-04-23T13:02:56Z

+
+| Variant | Color | Use | Limit |
+|---|---|---|---|
+| `primary` | Blue | The single most important action | **One per screen section** |


should we assoicate them with the color token? or is the general "blue" description better?

Kathrin Holzmann (Lelith) · 2026-04-23T13:04:35Z

+**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"


In forma36 texts should not be part of any of the component and all content and copy should come from outside and be translateable. So I think we should not have it in this skill

Kathrin Holzmann (Lelith) · 2026-04-23T13:07:22Z

+
+## TextLink
+
+For navigation and low-priority actions. Never use Button for navigation.


Never use Button for navigation could be misleading as we can render the Button as an a tag which would allow to use the Button for navigation.

This is also in contradiction of how we describe the Button earlier in the document.

Sometimes interactive Buttons e.g. "Edit" action has to be a link, because it leads the user to the edit-route

Kathrin Holzmann (Lelith) · 2026-04-23T13:09:07Z

+
+| Prop | Type | Notes |
+|---|---|---|
+| `as` | `'a'` (default) or `'button'` | `a` = navigation, `button` = action |


Kathrin Holzmann (Lelith) · 2026-04-23T13:39:31Z

+<Badge variant="positive">Published</Badge>
+<Badge variant="warning">Draft</Badge>


We should not use examples that are meant to be an EntityBadge component

Kathrin Holzmann (Lelith) · 2026-04-23T13:40:19Z

+|---|---|
+| `primary` | Default |
+| `primary-filled` | Emphasized default |
+| `positive` | Published, active |


we should not use the published association as this is meant for the EntityBadge

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>

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>

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>

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>

…ections, token compliance 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>

damann and others added 8 commits April 13, 2026 15:58

Create Forma 36 skill documentation

0a5567f

Add Forma 36 skill documentation for UI development using Contentful's design system, including rules, guidelines, and component usage.

Rename forma-36-skill to SKILL.md

f0032be

Add tokens skill

e3e3ff3

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.

Add UI Patterns skill

4c6d7c7

small formatting change in SKILL

7286e2b

Add description for Forma 36 UI design system.

Rename ui-patterns.md to screen-patterns.md

0af84aa

Rename UI Patterns to Screen Patterns

83fcb72

Updated the title to reflect 'Screen Patterns' instead of 'UI Patterns'.

toniwowtscherk requested review from a team and damann as code owners April 17, 2026 07:57

vercel Bot deployed to Preview – forma-36 April 17, 2026 08:01 View deployment

vercel Bot deployed to Preview – forma-36-storybook April 17, 2026 08:04 View deployment

Kathrin Holzmann (Lelith) reviewed Apr 27, 2026

View reviewed changes

vercel Bot deployed to Preview – forma-36 April 27, 2026 15:07 View deployment

vercel Bot deployed to Preview – forma-36-storybook April 27, 2026 15:09 View deployment

vercel Bot deployed to Preview – forma-36 April 29, 2026 09:36 View deployment

vercel Bot deployed to Preview – forma-36-storybook April 29, 2026 09:39 View deployment

vercel Bot deployed to Preview – forma-36 April 30, 2026 08:07 View deployment

vercel Bot deployed to Preview – forma-36-storybook April 30, 2026 08:10 View deployment

vercel Bot deployed to Preview – forma-36 April 30, 2026 08:57 View deployment

vercel Bot deployed to Preview – forma-36-storybook April 30, 2026 08:59 View deployment

vercel Bot deployed to Preview – forma-36 April 30, 2026 14:07 View deployment

vercel Bot deployed to Preview – forma-36-storybook April 30, 2026 14:10 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Restructure Forma 36 skill into granular guidelines format#3385

Restructure Forma 36 skill into granular guidelines format#3385
toniwowtscherk wants to merge 13 commits intomainfrom
forma36-skill

toniwowtscherk commented Apr 17, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Apr 17, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Apr 17, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Apr 17, 2026 •

edited

Loading

Uh oh!

Kathrin Holzmann (Lelith) Apr 23, 2026

Uh oh!

Kathrin Holzmann (Lelith) Apr 23, 2026

Uh oh!

Kathrin Holzmann (Lelith) Apr 23, 2026

Uh oh!

Kathrin Holzmann (Lelith) Apr 23, 2026

Uh oh!

Kathrin Holzmann (Lelith) Apr 23, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Kathrin Holzmann (Lelith) Apr 23, 2026

Uh oh!

Kathrin Holzmann (Lelith) Apr 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants


		## TextLink

		For navigation and low-priority actions. Never use Button for navigation.

	\| `as` \| `'a'` (default) or `'button'` \| `a` = navigation, `button` = action \|
	\| `as` \| `'a'` (default) or `'button'` \| `a` should be used for navigation between routes, `button` reserved only for interaction \|

		<Badge variant="positive">Published</Badge>
		<Badge variant="warning">Draft</Badge>

Conversation

toniwowtscherk commented Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Structure

What changed from the initial skill files

Key rules enforced

Test plan

Uh oh!

changeset-bot Bot commented Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

vercel Bot commented Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

size-limit report 📦

Uh oh!

Kathrin Holzmann (Lelith) Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Kathrin Holzmann (Lelith) Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Kathrin Holzmann (Lelith) Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Kathrin Holzmann (Lelith) Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Kathrin Holzmann (Lelith) Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Kathrin Holzmann (Lelith) Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Kathrin Holzmann (Lelith) Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

toniwowtscherk commented Apr 17, 2026 •

edited

Loading

changeset-bot Bot commented Apr 17, 2026 •

edited

Loading

vercel Bot commented Apr 17, 2026 •

edited

Loading

github-actions Bot commented Apr 17, 2026 •

edited

Loading