feat: AI.md Documentation (tokens & components) by joelharkes · Pull Request #2620 · Frontify/fondue

joelharkes · 2026-02-10T10:31:38Z

This adds documentation that can be used by AI to better work with Fondue.
It also add claude commands to regenerate the documentation 🤯

Why?

We can reference to these files/urls in web-app (as they are publicly available).
This hopefully improves our generate code quality.

Considerations

I haven't yet tested their effectiveness. (will be on this now)
I was thinking about maybe not including Grid/Flex stuff, personally i don't use it a lot, i prefer using just tailwind classes. What do you think?
I let it mention the underneath Radix component as I found this is really helpful when debugging weird behaviour with claude.
Please read through the documentation if it makes sense, I did an initial read
- maybe split button could use extra explainer when to use it?

Scope

I left other stuff out of scope:

fondue => legacy right? so we better not want to promote this
icons => probably better as mcp sever with search (or just let claude check file system in node modules for available icons)
chats => haven't used, not sure if it makes sense for ai.md.

Next steps

Do some try runs with this documentation and withouth
Add documentation from figma => tailwind class map that ai can use. (maybe something grep friendly)

changeset-bot · 2026-02-10T10:31:43Z

⚠️ No Changeset found

Latest commit: 78bbd6c

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

github-actions · 2026-02-10T10:34:27Z

PR Preview Action v1.6.2
🚀 View preview at https://Frontify.github.io/fondue/pr-preview/pr-2620/
Built to branch `gh-pages` at 2026-02-16 07:26 UTC. Preview will be ready when the GitHub Pages deployment is complete.

packages/tokens/AI.md

noahwaldner · 2026-02-10T12:18:49Z

packages/tokens/AI.md

+
+Use for paragraph text, labels, descriptions, and general UI copy.
+
+| Class | When to use |


Is it validated that this aligns with how the designers use it?

noahwaldner · 2026-02-10T12:19:47Z

packages/tokens/AI.md

+
+Each heading has a **`-strong`** (bold) variant for extra emphasis. Example: `tw-heading-large-strong`
+
+### Font Family (rarely needed directly)


noahwaldner · 2026-02-10T12:20:33Z

packages/tokens/AI.md

+
+### Primary Colors
+
+For main actions, CTAs, links, and brand elements.


is it validated this aligns with design?

noahwaldner · 2026-02-10T12:21:37Z

packages/tokens/AI.md

+
+| Class | When to use |
+|---|---|
+| `tw-bg-overlay` | Modal/dialog backdrop scrim |


is it validated this aligns with designers usage guides?

noahwaldner · 2026-02-10T12:21:52Z

packages/tokens/AI.md

+**Only** for data visualization (charts, graphs, plots). Do not use for UI elements.
+
+| Class | Purpose |
+|---|---|


is it validated this aligns with the analytics team?

noahwaldner · 2026-02-10T12:24:37Z

packages/tokens/AI.md

@@ -0,0 +1,320 @@
+# Fondue Design Tokens — Tailwind Class Reference for AI


Too many things are made up. These docs need to be audited carefully to not hallucinate and align with the guidelines by the designers.

Most likely this should be linked the the docs that are currently being created
https://fondue.frontify.com/document/51#/-/colors

valid point. the website linked though is very limited. i could make a claude command to extract info from here but i think there is not enough info there yet. ill check with the designers, joanna and bubo how we can best solve this :)

noahwaldner · 2026-02-10T12:27:37Z

packages/components/AI.md

@@ -0,0 +1,455 @@
+# Fondue Components — React Component Reference for AI


These docs are duplicates of the information available within the mcp server.

The docs should be added as component desicriptions to also be available through the mcp, manifest and storybook UI

http://localhost:6006/manifests
http://localhost:6006/mcp

yes its duplicate, the idea is to have a simpler alternative to avoid having to run an mcp server and make it work a bit more out of the box. I totally agree this should align with the designers documentation, i will look into this and improve the docs.

noahwaldner · 2026-02-10T12:28:36Z

packages/components/AI.md

@@ -0,0 +1,455 @@
+# Fondue Components — React Component Reference for AI
+
+This document describes the React components exported by `@frontify/fondue-components`. All components are TypeScript-first, support ref forwarding, and are theme-aware via Fondue design tokens. Most interactive components are built on [Radix UI](https://www.radix-ui.com/) primitives for accessibility (keyboard navigation, ARIA attributes, focus management).


Referencing Radix will most likely be misleading for a LLM as it is not relevant for the usage but might lead to it using a radix prop which is not exposed

valid point, ill do some experimenting and see. I found it was helpful as it does help sometimes suggest that we should start adding a radix prop to make a functionality work. so let me try out some more stuff here.

joelharkes added 2 commits February 10, 2026 11:00

add ai documentation for tailwind tokens

75e77b4

add components ai documentation

c55875d

joelharkes self-assigned this Feb 10, 2026

joelharkes requested a review from a team as a code owner February 10, 2026 10:31

joelharkes requested a review from noahwaldner February 10, 2026 10:31

noahwaldner reviewed Feb 10, 2026

View reviewed changes

packages/tokens/AI.md Outdated Show resolved Hide resolved

noahwaldner requested changes Feb 10, 2026

View reviewed changes

joelharkes added 6 commits February 11, 2026 05:18

update documentation

2b0664f

cleanup import

a4765f2

update docs

ccdf120

add split button doc

43ab851

fix plugin generation

f3471d6

Merge branch 'main' into ai-tokens-md

3568366

joelharkes changed the title ~~feat: AI.md Documentation (tokens & compnents)~~ feat: AI.md Documentation (tokens & components) Feb 11, 2026

joelharkes added 6 commits February 11, 2026 13:12

add accordion documentation

0e8e55b

add designer description

0c0dd5b

update docs

91787a3

update documentation

26c74c1

improve doc consistency

6aae6db

update docs

78bbd6c

joelharkes marked this pull request as draft February 16, 2026 07:25


		Use for paragraph text, labels, descriptions, and general UI copy.

		\| Class \| When to use \|


		Each heading has a `-strong` (bold) variant for extra emphasis. Example: `tw-heading-large-strong`

		### Font Family (rarely needed directly)


		### Primary Colors

		For main actions, CTAs, links, and brand elements.

		@@ -0,0 +1,320 @@
		# Fondue Design Tokens — Tailwind Class Reference for AI

		@@ -0,0 +1,455 @@
		# Fondue Components — React Component Reference for AI

		@@ -0,0 +1,455 @@
		# Fondue Components — React Component Reference for AI

		This document describes the React components exported by `@frontify/fondue-components`. All components are TypeScript-first, support ref forwarding, and are theme-aware via Fondue design tokens. Most interactive components are built on [Radix UI](https://www.radix-ui.com/) primitives for accessibility (keyboard navigation, ARIA attributes, focus management).

Conversation

joelharkes commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why?

Considerations

Scope

Next steps

Uh oh!

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

Uh oh!

⚠️ No Changeset found

Uh oh!

github-actions bot commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Built to branch gh-pages at 2026-02-16 07:26 UTC. Preview will be ready when the GitHub Pages deployment is complete.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Comments

joelharkes commented Feb 10, 2026 •

edited

Loading

changeset-bot bot commented Feb 10, 2026 •

edited

Loading

github-actions bot commented Feb 10, 2026 •

edited

Loading

Built to branch `gh-pages` at 2026-02-16 07:26 UTC.
Preview will be ready when the GitHub Pages deployment is complete.