create-ux-guidelines

name	create-ux-guidelines
description	Help make your own UX Guidelines for your design system, providing a common structure for developers and designers.

Create UX Guidelines Skill

Use this skill to write practical component guidelines that help people, design tools, and coding agents use a Web Component system correctly.

Treat guidelines as the authored layer between component implementation and generated metadata. - Component source defines behavior. - API metadata defines public attributes, properties, events, slots, CSS parts, and CSS variables. - Guidelines provide the structured content for the documentation site.

Good guidelines are not marketing copy. They are operating instructions for choosing, composing, reviewing, and shipping components.

Guidelines Structure

Ensure all guidelines conform to a strict, predictable schema.

Header And Links

Provide clear, concise explanations of what the component is and what it does. Include URLs pointing to the relevant external resources (e.g., design files, component playgrounds, or code repositories).

Named Slots

When a component exposes named slots, list their exact, case-sensitive names before Usage so people can discover the valid values quickly. Source this list from the component API metadata and omit the default slot. Include a short description such as "Use these names on items slotted inside this component."

Usage

Outline when and how to use the component. Reserve this for functional rules (e.g., "Reserve buttons for core actions").

Accessibility

Split accessibility guidance into distinct audiences:

• Designer: Guidelines for design-time considerations (e.g., "Never put tooltips on disabled buttons").
• Engineer: Guidelines for implementation considerations (e.g., "Ensure buttons are focusable via keyboard navigation", "Use appropriate ARIA roles").

Anatomy

Name the stable visible structure of a component. Anatomy images should use numbered callouts to identify the important parts of the component. Each number must map to a short written note so a person or agent can understand the guidance without relying on the image alone.

Variants

Use lightweight images to showcase the different states and variant configurations. Variants should map to real usage differences (e.g., Primary, Secondary, Icon-only).

Rules

Provide clear Do and Don't rules. Use these to visually compare correct versus incorrect usage and clarify nuanced design constraints.

Behaviour

Detail interactive states (Hover, Focus, Disabled) and how the component responds to user input.

Writing

Provide copywriting guidelines specific to the component (e.g., "Keep button text short and action-oriented. Use sentence case.").

Compositions

Use lightweight images to show realistic component combinations and use cases. Visual examples of slot placement and parent-child context are preferred over dense code snippets.

Publishing Guideline Assets

Keep guideline assets lightweight and URL-addressable. Anatomy, variant, rule, and composition images should support the written guidance rather than replace it.

A practical structure is:

• Store guideline text, metadata, and image URLs in a CMS or content source.
• Host images through a stable asset service or CDN.
• Expose the same structured content to a website, Figma workflow, or MCP server.
• Keep anatomy images numbered, with each number mapped to a short written explanation.

For a custom build, a headless CMS such as Contentful can hold guideline text, metadata, and image assets for a site like guides.example.com. A tool such as guides.gurusuite.xyz can provide the website and Figma plugin touchpoints from the same guideline content. For MCP usage, prefer returning structured text plus asset URLs. This lets agents reference the guidance and fetch or display supporting images when the client supports it.

Asset hosting can stay simple. Use the platform that matches the rest of the guideline system:

• Contentful Assets when guideline content and images are managed in a CMS.
• Vercel Blob when a Vercel-hosted site needs public image or media URLs.
• Netlify Blobs when a Netlify-hosted site needs project-native blob storage.
• Cloudflare R2 or another object store when assets should live outside the app host.
• Static repo assets when the system is small and Markdown-first.

Prefer stable, public, cacheable image URLs for guideline assets. Treat images as versioned assets where possible so agents, Figma plugins, MCP servers, and docs sites do not receive stale or broken references.

Third-party documentation tools such as ZeroHeight or Figma can also host guideline content. Use them when they fit the team's workflow, but keep a portable source of truth when agents, websites, or design tools all need access to the same guideline data.

Related Resources

List related component links to help users find alternatives.