Search the docs, videos, blog, apps, teams, skills and release notes.
At a glance
What it is
Component library design expertise covering design system tokens, component API design, compound components, polymorphic components, accessibility by default, Storybook documentation, testing, versioning, and tree-shaking.
A skill is a written procedure a bot loads when a job calls for it. This one is a single file, SKILL.md, and the whole file is on this page.
The whole file, exactly as it downloads. Read it before you rely on it.
SKILL.md
565 lines · 2,044 words
Design and build production-grade component libraries that serve as the foundation of a design system. This skill covers API design principles, accessibility integration, documentation, testing strategy, packaging, and long-term maintenance.
Component library design expertise covering design system tokens, component API design, compound components, polymorphic components, accessibility by default, Storybook documentation, testing, versioning, and tree-shaking.
Nothing. It ships with Murage, which is open source. Your bots run on the AI plan you already have.
Yes. Open it in Settings → Skills to read, edit or duplicate it. Skill Guard scans it again after every edit.
Download the app, connect the AI you already pay for, and tell your Chief of Staff what needs doing. Plan on about ten minutes from install to a working team.
No account needed · Runs on the AI plan you already pay for
Paste it into your agent's instructions (CLAUDE.md, AGENTS.md or a custom GPT), or add it to a bot in Murage.
Ask Ember for the bot, then switch the skill on in its settings.
Step 1
Send your Chief of Staff this message. It proposes the bot and its role first, and creates it when you say go.
Send this to Ember
“Create a bot that uses the Component Library skill, and show me the plan first.”
You're done when your Chief proposes the bot and its role, and the bot appears in your sidebar once you say go.
Step 2
You're done when you see the bot’s skills and the library.
Step 3
You're done when the skill shows as on for that bot.
Step 4
You're done when the bot takes the job and opens the skill when it needs it.
Prefer to do it yourself? Choose + in the sidebar, then New Bot.Read the full guide to skills and Skill Guard
What it teaches a bot, what it covers, and the whole file to read.
What it covers
Purpose
Design System Token Architecture
Component API Design
Compound Components
Polymorphic Components
Accessibility by Default
Storybook Documentation
Testing Components
Versioning and Release Strategy
Tree-Shaking and Package Build
Component Library Checklist
When to Use
Output Format
Example
Edge Cases
Layer 1: Global Tokens (Primitives)
Raw design values with no semantic meaning.
--color-blue-500: #3b82f6
--space-4: 1rem
--font-size-16: 1rem
Layer 2: Alias Tokens (Semantic)
Intent-based mapping to primitives.
--color-brand-primary: var(--color-blue-500)
--color-text-primary: var(--color-gray-900)
--spacing-component-gap: var(--space-4)
Layer 3: Component Tokens
Scoped to specific components.
--button-bg: var(--color-brand-primary)
--button-text: var(--color-white)
--button-radius: var(--radius-md)
--button-padding-x: var(--space-4)
--button-padding-y: var(--space-2)tokens/
colors.ts # Color primitives and semantic mappings
spacing.ts # Spacing scale
typography.ts # Font families, sizes, weights, line-heights
borders.ts # Border widths, radii
shadows.ts # Elevation system
motion.ts # Duration, easing curves
breakpoints.ts # Responsive breakpoints
z-index.ts # Z-index scale
index.ts # Combined export// tokens/colors.ts
export const colors = {
primitives: {
blue: { 50: '#eff6ff', 100: '#dbeafe', 500: '#3b82f6', 700: '#1d4ed8', 900: '#1e3a5c' },
gray: { 50: '#f9fafb', 100: '#f3f4f6', 500: '#6b7280', 700: '#374151', 900: '#111827' },
red: { 50: '#fef2f2', 500: '#ef4444', 700: '#b91c1c' },
green: { 50: '#f0fdf4', 500: '#22c55e', 700: '#15803d' },
},
semantic: {
brand: { primary: '{blue.500}', hover: '{blue.700}' },
text: { primary: '{gray.900}', secondary: '{gray.500}', inverse: '{gray.50}' },
bg: { primary: '#ffffff', secondary: '{gray.50}', surface: '{gray.100}' },
border: { default: '{gray.200}', focus: '{blue.500}' },
status: {
success: { text: '{green.700}', bg: '{green.50}' },
error: { text: '{red.700}', bg: '{red.50}' },
},
},
} as const;1. SIMPLE THINGS SHOULD BE SIMPLE
<Button>Save</Button> -- 90% of usage
<Button variant="danger" size="lg"> -- customization when needed
2. PROGRESSIVE DISCLOSURE
Common props are top-level.
Advanced props are grouped or use compound pattern.
3. CONSISTENT PROP NAMING
variant (not type, kind, style)
size (not sz, sizing)
disabled (boolean, not isDisabled)
onValueChange (not onChange, onUpdate, handleChange)
4. SENSIBLE DEFAULTS
Every prop should have a default that covers the most common case.
<Input type="text" /> -- type defaults to "text"
<Button variant="primary" size="md" /> -- variant and size have defaults
5. COMPOSITION OVER CONFIGURATION
Prefer compound components over mega-props.
BAD: <Select options={[]} renderOption={} renderGroup={} />
GOOD: <Select><Select.Option /><Select.Group /></Select>interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
/** Visual style variant */
variant?: 'primary' | 'secondary' | 'outline' | 'ghost' | 'danger';
/** Size of the button */
size?: 'sm' | 'md' | 'lg';
/** Show loading spinner and disable interaction */
loading?: boolean;
/** Content before the button label */
leftIcon?: React.ReactNode;
/** Content after the button label */
rightIcon?: React.ReactNode;
/** Full width of parent container */
fullWidth?: boolean;
/** Render as a different element (e.g., anchor) */
asChild?: boolean;
}
const Button = forwardRef<HTMLButtonElement, ButtonProps>(
({ variant = 'primary', size = 'md', loading, leftIcon, rightIcon,
fullWidth, disabled, children, className, asChild, ...props }, ref) => {
const isDisabled = disabled || loading;
const classes = cn(
'button',
`button--${variant}`,
`button--${size}`,
fullWidth && 'button--full',
isDisabled && 'button--disabled',
className,
);
return (
<button ref={ref} className={classes} disabled={isDisabled}
aria-busy={loading || undefined} {...props}>
{loading && <Spinner size={size} aria-hidden="true" />}
{!loading && leftIcon && <span className="button__icon">{leftIcon}</span>}
<span className="button__label">{children}</span>
{rightIcon && <span className="button__icon">{rightIcon}</span>}
</button>
);
}
);
Button.displayName = 'Button';// Dialog compound component
const DialogContext = createContext<DialogContextValue | null>(null);
function useDialogContext() {
const ctx = useContext(DialogContext);
if (!ctx) throw new Error('Dialog components must be used within <Dialog>');
return ctx;
}
function Dialog({ open, onOpenChange, children }: DialogProps) {
return (
<DialogContext.Provider value={{ open, onOpenChange }}>
{children}
</DialogContext.Provider>
);
}
function DialogTrigger({ children, asChild }: DialogTriggerProps) {
const { onOpenChange } = useDialogContext();
return <button onClick={() => onOpenChange(true)}>{children}</button>;
}
function DialogContent({ children, title, description }: DialogContentProps) {
const { open, onOpenChange } = useDialogContext();
if (!open) return null;
return createPortal(
<div className="dialog-overlay" onClick={() => onOpenChange(false)}>
<div className="dialog-content" role="dialog" aria-modal="true"
aria-labelledby={title ? 'dialog-title' : undefined}
onClick={(e) => e.stopPropagation()}>
{title && <h2 id="dialog-title">{title}</h2>}
{description && <p id="dialog-desc">{description}</p>}
{children}
</div>
</div>,
document.body
);
}
function DialogClose({ children }: { children: React.ReactNode }) {
const { onOpenChange } = useDialogContext();
return <button onClick={() => onOpenChange(false)}>{children}</button>;
}
Dialog.Trigger = DialogTrigger;
Dialog.Content = DialogContent;
Dialog.Close = DialogClose;
// Usage
<Dialog open={isOpen} onOpenChange={setIsOpen}>
<Dialog.Trigger>Open Settings</Dialog.Trigger>
<Dialog.Content title="Settings">
<p>Configure your preferences.</p>
<Dialog.Close>Done</Dialog.Close>
</Dialog.Content>
</Dialog>// Type-safe polymorphic `as` prop
type PolymorphicRef<C extends React.ElementType> = React.ComponentPropsWithRef<C>['ref'];
type PolymorphicProps<C extends React.ElementType, Props = {}> = Props & {
as?: C;
} & Omit<React.ComponentPropsWithoutRef<C>, keyof Props | 'as'>;
type PolymorphicPropsWithRef<C extends React.ElementType, Props = {}> =
PolymorphicProps<C, Props> & { ref?: PolymorphicRef<C> };
// Usage in component
type TextProps<C extends React.ElementType = 'span'> = PolymorphicPropsWithRef<C, {
variant?: 'body' | 'heading' | 'caption' | 'code';
size?: 'sm' | 'md' | 'lg';
weight?: 'regular' | 'medium' | 'bold';
}>;
function Text<C extends React.ElementType = 'span'>({
as, variant = 'body', size = 'md', weight = 'regular',
className, children, ...props
}: TextProps<C>) {
const Component = as || 'span';
return (
<Component className={cn('text', `text--${variant}`, `text--${size}`, className)} {...props}>
{children}
</Component>
);
}
// Usage
<Text>Default span</Text>
<Text as="h1" variant="heading" size="lg">Page Title</Text>
<Text as="a" href="/about">Link text</Text>
<Text as="label" htmlFor="email">Email</Text>// All interactive components must include:
// 1. Keyboard support
// 2. ARIA attributes
// 3. Focus management
// 4. Screen reader announcements
// Example: Switch component with built-in a11y
function Switch({ checked, onCheckedChange, label, id }: SwitchProps) {
const switchId = id || useId();
return (
<div className="switch-wrapper">
<label htmlFor={switchId} className="switch-label">{label}</label>
<button
id={switchId}
role="switch"
aria-checked={checked}
onClick={() => onCheckedChange(!checked)}
onKeyDown={(e) => {
if (e.key === ' ' || e.key === 'Enter') {
e.preventDefault();
onCheckedChange(!checked);
}
}}
className={cn('switch', checked && 'switch--checked')}
>
<span className="switch-thumb" />
</button>
</div>
);
}
// A11y testing in every component test
test('Switch is accessible', async () => {
const { container } = render(<Switch label="Dark mode" checked={false} onCheckedChange={() => {}} />);
expect(await axe(container)).toHaveNoViolations();
});[ ] Has visible label or aria-label
[ ] Keyboard operable (Tab, Enter, Space, Escape, Arrow keys as appropriate)
[ ] Focus indicator visible
[ ] Color contrast meets WCAG AA
[ ] Works with screen readers (test with NVDA/VoiceOver)
[ ] Supports prefers-reduced-motion
[ ] Error states have aria-invalid and aria-describedby
[ ] Loading states have aria-busy
[ ] Dynamic content uses aria-live
[ ] Touch target at least 24x24px// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';
const meta: Meta<typeof Button> = {
title: 'Components/Button',
component: Button,
tags: ['autodocs'],
argTypes: {
variant: {
control: 'select',
options: ['primary', 'secondary', 'outline', 'ghost', 'danger'],
description: 'Visual style of the button',
table: { defaultValue: { summary: 'primary' } },
},
size: {
control: 'radio',
options: ['sm', 'md', 'lg'],
},
loading: { control: 'boolean' },
disabled: { control: 'boolean' },
onClick: { action: 'clicked' },
},
parameters: {
docs: {
description: {
component: 'Primary UI component for user interaction.',
},
},
},
};
export default meta;
type Story = StoryObj<typeof Button>;
export const Primary: Story = {
args: { children: 'Button', variant: 'primary' },
};
export const AllVariants: Story = {
render: () => (
<div style={{ display: 'flex', gap: '1rem' }}>
<Button variant="primary">Primary</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="outline">Outline</Button>
<Button variant="ghost">Ghost</Button>
<Button variant="danger">Danger</Button>
</div>
),
};
export const Loading: Story = {
args: { children: 'Saving...', loading: true },
};// Unit test with Testing Library
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
describe('Button', () => {
it('renders with correct text', () => {
render(<Button>Click me</Button>);
expect(screen.getByRole('button', { name: 'Click me' })).toBeInTheDocument();
});
it('calls onClick when clicked', async () => {
const onClick = vi.fn();
render(<Button onClick={onClick}>Click me</Button>);
await userEvent.click(screen.getByRole('button'));
expect(onClick).toHaveBeenCalledOnce();
});
it('does not call onClick when disabled', async () => {
const onClick = vi.fn();
render(<Button onClick={onClick} disabled>Click me</Button>);
await userEvent.click(screen.getByRole('button'));
expect(onClick).not.toHaveBeenCalled();
});
it('shows spinner when loading', () => {
render(<Button loading>Save</Button>);
expect(screen.getByRole('button')).toHaveAttribute('aria-busy', 'true');
});
it('passes axe accessibility checks', async () => {
const { container } = render(<Button>Accessible</Button>);
expect(await axe(container)).toHaveNoViolations();
});
});
// Visual regression with Chromatic or Playwright
// Snapshot each story automaticallyMAJOR (X.0.0): Breaking changes
- Removing a prop
- Changing default behavior
- Renaming a component
- Changing TypeScript types in breaking way
MINOR (0.X.0): New features (backwards compatible)
- Adding a new component
- Adding a new prop (with default value)
- Adding a new variant
PATCH (0.0.X): Bug fixes
- Fixing a visual bug
- Fixing a11y issue
- Fixing TypeScript type accuracy## [2.1.0] - 2025-03-15
### Added
- `Tooltip` component with hover and focus triggers
- `fullWidth` prop to `Button` component
### Fixed
- `Select` dropdown now correctly positions in scroll containers
- `Dialog` focus trap includes dynamically added elements
### Deprecated
- `Modal` component: use `Dialog` instead (will be removed in 3.0)// package.json
{
"name": "@myorg/ui",
"version": "2.1.0",
"sideEffects": ["*.css"],
"main": "dist/cjs/index.js",
"module": "dist/esm/index.js",
"types": "dist/types/index.d.ts",
"exports": {
".": {
"import": "./dist/esm/index.js",
"require": "./dist/cjs/index.js",
"types": "./dist/types/index.d.ts"
},
"./Button": {
"import": "./dist/esm/Button.js",
"require": "./dist/cjs/Button.js",
"types": "./dist/types/Button.d.ts"
},
"./styles.css": "./dist/styles.css"
},
"files": ["dist"]
}Token system defined (primitives -> semantic -> component tokens)
Component API follows consistent naming conventions
Every component has TypeScript types with JSDoc descriptions
Compound components used for complex composite UIs
Polymorphic as prop available on layout/text components
Every interactive component is keyboard accessible
Every component has Storybook stories with controls
Every component has unit tests + a11y tests
Visual regression tests configured (Chromatic or Playwright)
Package exports enable tree-shaking
sideEffects field correctly configured
Semantic versioning enforced via changesets
CHANGELOG maintained with each release
forwardRef used on all components that wrap native elements
Use this skill when:
Designing or implementing component library solutions
Reviewing or improving existing component library approaches
Making architectural or implementation decisions about component library
Learning component library patterns and best practices
Troubleshooting component library-related issues
Do NOT use this skill when:
The question is about a fundamentally different technology domain
A more specific sibling skill covers the exact topic needed
The user needs a complete hands-on tutorial rather than expert guidance
# Component Library Analysis
## Context Assessment
[Situation summary and constraints]
## Recommended Approach
[Primary recommendation with rationale]
## Implementation Steps
1. [Step with specific details]
2. [Step with specific details]
3. [Step with specific details]
## Trade-offs and Considerations
- [Key trade-off 1]
- [Key trade-off 2]
## Next Steps
- [Immediate action item]
- [Follow-up action item]Input: "Help me implement component library for a medium-scale production application"
Output: A structured analysis covering current state assessment, recommended component library approach with specific patterns, implementation roadmap with milestones, and risk mitigation strategies tailored to the application scale and constraints.
Legacy system integration: When component library must coexist with legacy approaches, provide a gradual migration path rather than a complete rewrite
Scale mismatch: When the solution complexity exceeds the project scale, recommend a simpler approach and note when to revisit
Team skill gaps: When the team lacks experience with the recommended approach, include learning resources and simpler alternatives
Conflicting requirements: When constraints conflict (e.g., performance vs. maintainability), explicitly state the trade-off and recommend based on stated priorities
SKILL.md
565 lines · 2,044 words
The text of SKILL.md is shown as it downloads, under the Apache-2.0 license, by Ferrox Labs. The license is the one in the file's own frontmatter.
Your new bot
Component Library bot
Waiting in your sidebar once you say go.
No account needed · Runs on the AI plan you already pay for