feat: add f0-design-buddy skill with design rules and contribution docs#3762
feat: add f0-design-buddy skill with design rules and contribution docs#3762eliseo-juan wants to merge 2 commits intomainfrom
Conversation
- Add .skills/f0-design-buddy/SKILL.md: collaborative design companion with 4-phase workflow (Discovery, Gatekeeping, Brainstorming, Challenge) - Add packages/react/docs/design-rules.mdx: F0 design rules as a Storybook Foundations page (color, spacing, typography, a11y, etc.) - Rewrite packages/react/docs/contributions.mdx: expanded contribution process with validation checklist, triage, collaboration phases, and FAQ - Update preview.tsx: add design-rules to foundation sidebar ordering
✅ No New Circular DependenciesNo new circular dependencies detected. Current count: 0 |
📦 Alpha Package Version PublishedUse Use |
🔍 Visual review for your branch is published 🔍Here are the links to: |
Coverage Report for packages/react
File CoverageNo changed files found. |
There was a problem hiding this comment.
Pull request overview
Adds a new “design buddy” skill and expands Storybook documentation so designers/devs can reference a canonical set of F0 design rules and an updated contribution process.
Changes:
- Added a new Foundations docs page documenting F0 design rules.
- Rewrote the contributions guide into a more complete process/checklist + standards reference.
- Updated Storybook sidebar ordering and introduced a new
.skills/f0-design-buddyskill.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
packages/react/docs/design-rules.mdx |
New “Foundations/Design rules” MDX page intended as canonical rules for tokens, a11y, composability, naming, etc. |
packages/react/docs/contributions.mdx |
Expanded contribution guide with validation checklist, triage, collaboration flow, standards, and FAQ. |
packages/react/.storybook/preview.tsx |
Added design-rules to foundationOrder for Foundations sidebar ordering. |
.skills/f0-design-buddy/SKILL.md |
New skill defining a 4-phase workflow for design iteration and rule-based challenge. |
packages/react/docs/design-rules.mdx
Outdated
| | `text-xs` | 0.6875rem (11px) | 1rem (16px) | — | | ||
| | `text-sm` | 0.8125rem (13px) | 1.25rem (20px) | — | | ||
| | `text-base` | 0.875rem (14px) | 1.25rem (20px) | — | | ||
| | `text-lg` | 1rem (16px) | 1.5rem (24px) | — | | ||
| | `text-xl` | 1.125rem (18px) | 1.5rem (24px) | -0.02em | | ||
| | `text-2xl` | 1.5rem (24px) | 2rem (32px) | -0.02em | | ||
|
|
||
| ### Rules | ||
|
|
||
| - Use the existing type scale — do not add custom `fontSize` values | ||
| - Pair text size with the correct semantic color (`f1-foreground`, `f1-foreground-secondary`) | ||
| - Larger headings (`xl`, `2xl`) have negative letter-spacing baked in — do not override |
There was a problem hiding this comment.
The typography scale table doesn't match the actual Tailwind theme values in packages/core/tailwind.ts (e.g., text-xs/text-sm/text-xl/text-2xl sizes and line-heights differ, and the config includes 3xl/4xl). Since this page is meant to be canonical, please align the table (and any tracking/letter-spacing notes) with the real theme.fontSize definitions.
| | `text-xs` | 0.6875rem (11px) | 1rem (16px) | — | | |
| | `text-sm` | 0.8125rem (13px) | 1.25rem (20px) | — | | |
| | `text-base` | 0.875rem (14px) | 1.25rem (20px) | — | | |
| | `text-lg` | 1rem (16px) | 1.5rem (24px) | — | | |
| | `text-xl` | 1.125rem (18px) | 1.5rem (24px) | -0.02em | | |
| | `text-2xl` | 1.5rem (24px) | 2rem (32px) | -0.02em | | |
| ### Rules | |
| - Use the existing type scale — do not add custom `fontSize` values | |
| - Pair text size with the correct semantic color (`f1-foreground`, `f1-foreground-secondary`) | |
| - Larger headings (`xl`, `2xl`) have negative letter-spacing baked in — do not override | |
| | `text-xs` | 0.75rem (12px) | 1rem (16px) | — | | |
| | `text-sm` | 0.875rem (14px) | 1.25rem (20px) | — | | |
| | `text-base` | 1rem (16px) | 1.5rem (24px) | — | | |
| | `text-lg` | 1.125rem (18px) | 1.75rem (28px) | — | | |
| | `text-xl` | 1.25rem (20px) | 1.75rem (28px) | — | | |
| | `text-2xl` | 1.5rem (24px) | 2rem (32px) | — | | |
| | `text-3xl` | 1.875rem (30px) | 2.25rem (36px) | — | | |
| | `text-4xl` | 2.25rem (36px) | 2.5rem (40px) | — | | |
| ### Rules | |
| - Use the existing type scale — do not add custom `fontSize` values | |
| - Pair text size with the correct semantic color (`f1-foreground`, `f1-foreground-secondary`) | |
| - Do not override letter-spacing unless you have a strong typographic reason |
packages/react/docs/design-rules.mdx
Outdated
| | Token | Effect | Use | | ||
| | ------------- | ---------------------- | ---------------------------- | | ||
| | `shadow` | 2px blur, 4% opacity | Subtle elevation (cards) | | ||
| | `shadow-md` | 4px blur, 8% opacity | Medium elevation (dropdowns) | | ||
| | `shadow-lg` | 8px blur, 12% opacity | High elevation (modals) | | ||
| | `shadow-xl` | 12px blur, 16% opacity | Maximum elevation (popovers) | | ||
| | `shadow-none` | No shadow | Flat elements | |
There was a problem hiding this comment.
The shadows table descriptions (blur amounts) don't match the actual Tailwind boxShadow tokens in packages/core/tailwind.ts (e.g., shadow is 0 2px 20px ... /0.04, shadow-lg is 0 8px 30px ... /0.12, etc.). Please update the “Effect” column to reflect the real offsets/blur and opacities so consumers don't implement the wrong elevation.
| | Token | Effect | Use | | |
| | ------------- | ---------------------- | ---------------------------- | | |
| | `shadow` | 2px blur, 4% opacity | Subtle elevation (cards) | | |
| | `shadow-md` | 4px blur, 8% opacity | Medium elevation (dropdowns) | | |
| | `shadow-lg` | 8px blur, 12% opacity | High elevation (modals) | | |
| | `shadow-xl` | 12px blur, 16% opacity | Maximum elevation (popovers) | | |
| | `shadow-none` | No shadow | Flat elements | | |
| | Token | Effect | Use | | |
| | ------------- | ------------------------------------------------------------- | ---------------------------- | | |
| | `shadow` | y-offset 2px, blur 20px, 4% opacity (`0 2px 20px ... / 0.04`) | Subtle elevation (cards) | | |
| | `shadow-md` | Medium elevation between `shadow` and `shadow-lg` as defined in Tailwind config | Medium elevation (dropdowns) | | |
| | `shadow-lg` | y-offset 8px, blur 30px, 12% opacity (`0 8px 30px ... / 0.12`)| High elevation (modals) | | |
| | `shadow-xl` | Strongest elevation, with larger offsets/blur and opacity than `shadow-lg` | Maximum elevation (popovers) | | |
| | `shadow-none` | No shadow (`0 0 0 ... / 0` opacity) | Flat elements | |
|
|
||
| - Components should do one thing well — avoid "god components" with dozens of props | ||
| - Use composition over configuration: prefer `children` and slots over boolean flags | ||
| - Never expose `className` as a public prop — it breaks encapsulation |
There was a problem hiding this comment.
This rule says to never expose className as a public prop, but some public APIs currently do (e.g. F0FormPropsWithSingleSchema.className in packages/react/src/components/F0Form/types.ts). Either soften/clarify this rule as guidance for new components (and mention legacy exceptions), or align the existing APIs so the documentation stays truthful.
| - Never expose `className` as a public prop — it breaks encapsulation | |
| - For new components, avoid exposing `className` as a public prop — it breaks encapsulation | |
| - Existing public components that already expose `className` are legacy exceptions and should not be used as a pattern for new APIs |
| "borders", | ||
| "shadows", | ||
| "icons", | ||
| "design-rules", | ||
| ] |
There was a problem hiding this comment.
This foundationOrder block is only reached when the earlier foundations detection logic matches (it checks for foundations/ and then does split("/")). Story IDs/links in this repo look hyphenated (e.g. foundations-design-rules--docs), so the foundations sub-sorting likely never runs and foundationOrder (including design-rules) won't affect sidebar ordering. Consider basing the foundations detection/splitting on title (which includes Foundations/...) or adjusting the parsing to match the actual Storybook IDs.
- Add Storybook URL conventions and proactive linking behavior to f0-design-buddy skill - Add designer-first language rule to skill - Refactor design-rules.mdx to reference token source files instead of duplicating values - Add golden rule: never create new tokens without F0 core team decision
Summary
.skills/f0-design-buddy/SKILL.md— a collaborative design companion that helps designers and developers iterate on UI ideas, challenge designs against F0 rules, and decide whether something belongs in F0 or should stay local. 4-phase workflow: Discovery → Gatekeeping → Brainstorming → Challenge.packages/react/docs/design-rules.mdx— documents all F0 design rules (color tokens, typography, spacing, border radius, shadows, accessibility, composability, naming, maturity, responsiveness) as a Foundations page.packages/react/docs/contributions.mdx— expanded from 82 lines to a comprehensive guide with validation checklist, triage decisions, collaboration phases, quality standards, and FAQ.design-rulesto thefoundationOrderarray inpreview.tsx.How it works
The SKILL.md defines agent behavior (phases, anti-patterns, decision trees). It references the two MDX files as canonical source of truth — so both humans (via Storybook) and AI agents (via file reads) use the same design rules and contribution process.
Checklist