Web Component Design
Seth HobsonCommunityCreated by Seth Hobson
- Skill
- Guidelines
- Software development
- MIT
- No issues found
AutoGineer summary
Written by AutoGineer from the skill’s own files, not by the author
This skill provides a comprehensive guide to building reusable and maintainable UI components. It covers essential architectural patterns like compound components and render props, alongside various CSS-in-JS styling approaches. It includes practical implementation examples for React, Vue, and Svelte, focusing on API design, accessibility, and framework-specific features like Vue composables and Svelte runes.
What it does
- Explains component composition patterns including compound components and render props.
- Compares CSS-in-JS and styling methodologies like Tailwind CSS, CSS Modules, and Vanilla Extract.
- Provides guidance on designing consistent and semantic component APIs.
- Demonstrates framework-specific implementations for React, Vue 3, and Svelte 5.
- Offers best practices for accessibility, state management, and refactoring.
- Includes reference patterns for common UI elements like modals and tab systems.
When to use it
- When designing or maintaining a UI component library or design system.
- When implementing complex component composition to share state or logic.
- When choosing a styling strategy for a new or existing frontend project.
- When refactoring legacy components into modern, reusable patterns.
- When standardizing component APIs across a large codebase.
Advantages
- Promotes clean, modular, and reusable code structures.
- Provides clear patterns for handling component state and logic sharing.
- Offers actionable advice on accessibility and semantic API design.
- Supports multiple modern frameworks with specific implementation examples.
- Helps prevent common issues like prop drilling and style conflicts.
Usage examples
- “How do I implement a compound component pattern in React?”
- The skill provides a step-by-step example using React Context to share state between a parent component and its children, such as an Accordion or Tabs system.
- “What are the best ways to style components in a design system?”
- The skill outlines various approaches including Tailwind CSS for utility classes, CSS Modules for scoping, and zero-runtime solutions like Vanilla Extract.
- “How can I make my custom UI components more accessible?”
- The skill provides patterns for ARIA attributes, keyboard navigation, and focus management, specifically demonstrated through modal and dropdown implementations.
- “Show me how to use Svelte 5 runes for component props.”
- The skill provides a code example demonstrating the use of $props() and $derived() to manage component state and reactivity in Svelte 5.
Install
Download the skill as a ZIP:
https://autogineer.com/agent-skills/wshobson/web-component-design/downloadUnzip it into the cross-client skills folder of your project:
mkdir -p .agents/skills && unzip web-component-design.zip -d .agents/skills
Documentation by Seth Hobson
Web Component Design
Build reusable, maintainable UI components using modern frameworks with clean composition patterns and styling approaches.
When to Use This Skill
Designing reusable component libraries or design systems
Implementing complex component composition patterns
Choosing and applying CSS-in-JS solutions
Building accessible, responsive UI components
Creating consistent component APIs across a codebase
Refactoring legacy components into modern patterns
Implementing compound components or render props
Core Concepts
1. Component Composition Patterns
Compound Components: Related components that work together
// Usage
<Select value={value} onChange={setValue}>
<Select.Trigger>Choose option</Select.Trigger>
<Select.Options>
<Select.Option value="a">Option A</Select.Option>
<Select.Option value="b">Option B</Select.Option>
</Select.Options>
</Select>Render Props: Delegate rendering to parent
<DataFetcher url="/api/users">
{({ data, loading, error }) =>
loading ? <Spinner /> : <UserList users={data} />
}
</DataFetcher>Slots (Vue/Svelte): Named content injection points
<template>
<Card>
<template #header>Title</template>
<template #content>Body text</template>
<template #footer><Button>Action</Button></template>
</Card>
</template>2. CSS-in-JS Approaches
| Solution | Approach | Best For |
|---|---|---|
| Tailwind CSS | Utility classes | Rapid prototyping, design systems |
| CSS Modules | Scoped CSS files | Existing CSS, gradual adoption |
| styled-components | Template literals | React, dynamic styling |
| Emotion | Object/template styles | Flexible, SSR-friendly |
| Vanilla Extract | Zero-runtime | Performance-critical apps |
3. Component API Design
interface ButtonProps {
variant?: "primary" | "secondary" | "ghost";
size?: "sm" | "md" | "lg";
isLoading?: boolean;
isDisabled?: boolean;
leftIcon?: React.ReactNode;
rightIcon?: React.ReactNode;
children: React.ReactNode;
onClick?: () => void;
}Principles:
Use semantic prop names (
isLoadingvsloading)Provide sensible defaults
Support composition via
childrenAllow style overrides via
classNameorstyle
Quick Start: React Component with Tailwind
import { forwardRef, type ComponentPropsWithoutRef } from "react";
import { cva, type VariantProps } from "class-variance-authority";
import { cn } from "@/lib/utils";
const buttonVariants = cva(
"inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 disabled:pointer-events-none disabled:opacity-50",
{
variants: {
variant: {
primary: "bg-blue-600 text-white hover:bg-blue-700",
secondary: "bg-gray-100 text-gray-900 hover:bg-gray-200",
ghost: "hover:bg-gray-100 hover:text-gray-900",
},
size: {
sm: "h-8 px-3 text-sm",
md: "h-10 px-4 text-sm",
lg: "h-12 px-6 text-base",
},
},
defaultVariants: {
variant: "primary",
size: "md",
},
},
);
interface ButtonProps
extends
ComponentPropsWithoutRef<"button">,
VariantProps<typeof buttonVariants> {
isLoading?: boolean;
}
export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
({ className, variant, size, isLoading, children, ...props }, ref) => (
<button
ref={ref}
className={cn(buttonVariants({ variant, size }), className)}
disabled={isLoading || props.disabled}
{...props}
>
{isLoading && <Spinner className="mr-2 h-4 w-4" />}
{children}
</button>
),
);
Button.displayName = "Button";Framework Patterns
React: Compound Components
import { createContext, useContext, useState, type ReactNode } from "react";
interface AccordionContextValue {
openItems: Set<string>;
toggle: (id: string) => void;
}
const AccordionContext = createContext<AccordionContextValue | null>(null);
function useAccordion() {
const context = useContext(AccordionContext);
if (!context) throw new Error("Must be used within Accordion");
return context;
}
export function Accordion({ children }: { children: ReactNode }) {
const [openItems, setOpenItems] = useState<Set<string>>(new Set());
const toggle = (id: string) => {
setOpenItems((prev) => {
const next = new Set(prev);
next.has(id) ? next.delete(id) : next.add(id);
return next;
});
};
return (
<AccordionContext.Provider value={{ openItems, toggle }}>
<div className="divide-y">{children}</div>
</AccordionContext.Provider>
);
}
Accordion.Item = function AccordionItem({
id,
title,
children,
}: {
id: string;
title: string;
children: ReactNode;
}) {
const { openItems, toggle } = useAccordion();
const isOpen = openItems.has(id);
return (
<div>
<button onClick={() => toggle(id)} className="w-full text-left py-3">
{title}
</button>
{isOpen && <div className="pb-3">{children}</div>}
</div>
);
};Vue 3: Composables
<script setup lang="ts">
import { ref, computed, provide, inject, type InjectionKey } from "vue";
interface TabsContext {
activeTab: Ref<string>;
setActive: (id: string) => void;
}
const TabsKey: InjectionKey<TabsContext> = Symbol("tabs");
// Parent component
const activeTab = ref("tab-1");
provide(TabsKey, {
activeTab,
setActive: (id: string) => {
activeTab.value = id;
},
});
// Child component usage
const tabs = inject(TabsKey);
const isActive = computed(() => tabs?.activeTab.value === props.id);
</script>Svelte 5: Runes
<script lang="ts">
interface Props {
variant?: 'primary' | 'secondary';
size?: 'sm' | 'md' | 'lg';
onclick?: () => void;
children: import('svelte').Snippet;
}
let { variant = 'primary', size = 'md', onclick, children }: Props = $props();
const classes = $derived(
`btn btn-${variant} btn-${size}`
);
</script>
<button class={classes} {onclick}>
{@render children()}
</button>Best Practices
Single Responsibility: Each component does one thing well
Prop Drilling Prevention: Use context for deeply nested data
Accessible by Default: Include ARIA attributes, keyboard support
Controlled vs Uncontrolled: Support both patterns when appropriate
Forward Refs: Allow parent access to DOM nodes
Memoization: Use
React.memo,useMemofor expensive rendersError Boundaries: Wrap components that may fail
Common Issues
Prop Explosion: Too many props - consider composition instead
Style Conflicts: Use scoped styles or CSS Modules
Re-render Cascades: Profile with React DevTools, memo appropriately
Accessibility Gaps: Test with screen readers and keyboard navigation
Bundle Size: Tree-shake unused component variants
Files
- ATTRIBUTION.mdAdded by AutoGineer978 B
- LICENSELicence file added by AutoGineer1.0 KiB
- SKILL.md7.3 KiB
- references/accessibility-patterns.md15.5 KiB
- references/component-patterns.md9.5 KiB
- references/css-styling-approaches.md12.5 KiB
SKILL.md
Web Component Design
Build reusable, maintainable UI components using modern frameworks with clean composition patterns and styling approaches.
When to Use This Skill
Designing reusable component libraries or design systems
Implementing complex component composition patterns
Choosing and applying CSS-in-JS solutions
Building accessible, responsive UI components
Creating consistent component APIs across a codebase
Refactoring legacy components into modern patterns
Implementing compound components or render props
Core Concepts
1. Component Composition Patterns
Compound Components: Related components that work together
// Usage
<Select value={value} onChange={setValue}>
<Select.Trigger>Choose option</Select.Trigger>
<Select.Options>
<Select.Option value="a">Option A</Select.Option>
<Select.Option value="b">Option B</Select.Option>
</Select.Options>
</Select>Render Props: Delegate rendering to parent
<DataFetcher url="/api/users">
{({ data, loading, error }) =>
loading ? <Spinner /> : <UserList users={data} />
}
</DataFetcher>Slots (Vue/Svelte): Named content injection points
<template>
<Card>
<template #header>Title</template>
<template #content>Body text</template>
<template #footer><Button>Action</Button></template>
</Card>
</template>2. CSS-in-JS Approaches
| Solution | Approach | Best For |
|---|---|---|
| Tailwind CSS | Utility classes | Rapid prototyping, design systems |
| CSS Modules | Scoped CSS files | Existing CSS, gradual adoption |
| styled-components | Template literals | React, dynamic styling |
| Emotion | Object/template styles | Flexible, SSR-friendly |
| Vanilla Extract | Zero-runtime | Performance-critical apps |
3. Component API Design
interface ButtonProps {
variant?: "primary" | "secondary" | "ghost";
size?: "sm" | "md" | "lg";
isLoading?: boolean;
isDisabled?: boolean;
leftIcon?: React.ReactNode;
rightIcon?: React.ReactNode;
children: React.ReactNode;
onClick?: () => void;
}Principles:
Use semantic prop names (
isLoadingvsloading)Provide sensible defaults
Support composition via
childrenAllow style overrides via
classNameorstyle
Quick Start: React Component with Tailwind
import { forwardRef, type ComponentPropsWithoutRef } from "react";
import { cva, type VariantProps } from "class-variance-authority";
import { cn } from "@/lib/utils";
const buttonVariants = cva(
"inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 disabled:pointer-events-none disabled:opacity-50",
{
variants: {
variant: {
primary: "bg-blue-600 text-white hover:bg-blue-700",
secondary: "bg-gray-100 text-gray-900 hover:bg-gray-200",
ghost: "hover:bg-gray-100 hover:text-gray-900",
},
size: {
sm: "h-8 px-3 text-sm",
md: "h-10 px-4 text-sm",
lg: "h-12 px-6 text-base",
},
},
defaultVariants: {
variant: "primary",
size: "md",
},
},
);
interface ButtonProps
extends
ComponentPropsWithoutRef<"button">,
VariantProps<typeof buttonVariants> {
isLoading?: boolean;
}
export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
({ className, variant, size, isLoading, children, ...props }, ref) => (
<button
ref={ref}
className={cn(buttonVariants({ variant, size }), className)}
disabled={isLoading || props.disabled}
{...props}
>
{isLoading && <Spinner className="mr-2 h-4 w-4" />}
{children}
</button>
),
);
Button.displayName = "Button";Framework Patterns
React: Compound Components
import { createContext, useContext, useState, type ReactNode } from "react";
interface AccordionContextValue {
openItems: Set<string>;
toggle: (id: string) => void;
}
const AccordionContext = createContext<AccordionContextValue | null>(null);
function useAccordion() {
const context = useContext(AccordionContext);
if (!context) throw new Error("Must be used within Accordion");
return context;
}
export function Accordion({ children }: { children: ReactNode }) {
const [openItems, setOpenItems] = useState<Set<string>>(new Set());
const toggle = (id: string) => {
setOpenItems((prev) => {
const next = new Set(prev);
next.has(id) ? next.delete(id) : next.add(id);
return next;
});
};
return (
<AccordionContext.Provider value={{ openItems, toggle }}>
<div className="divide-y">{children}</div>
</AccordionContext.Provider>
);
}
Accordion.Item = function AccordionItem({
id,
title,
children,
}: {
id: string;
title: string;
children: ReactNode;
}) {
const { openItems, toggle } = useAccordion();
const isOpen = openItems.has(id);
return (
<div>
<button onClick={() => toggle(id)} className="w-full text-left py-3">
{title}
</button>
{isOpen && <div className="pb-3">{children}</div>}
</div>
);
};Vue 3: Composables
<script setup lang="ts">
import { ref, computed, provide, inject, type InjectionKey } from "vue";
interface TabsContext {
activeTab: Ref<string>;
setActive: (id: string) => void;
}
const TabsKey: InjectionKey<TabsContext> = Symbol("tabs");
// Parent component
const activeTab = ref("tab-1");
provide(TabsKey, {
activeTab,
setActive: (id: string) => {
activeTab.value = id;
},
});
// Child component usage
const tabs = inject(TabsKey);
const isActive = computed(() => tabs?.activeTab.value === props.id);
</script>Svelte 5: Runes
<script lang="ts">
interface Props {
variant?: 'primary' | 'secondary';
size?: 'sm' | 'md' | 'lg';
onclick?: () => void;
children: import('svelte').Snippet;
}
let { variant = 'primary', size = 'md', onclick, children }: Props = $props();
const classes = $derived(
`btn btn-${variant} btn-${size}`
);
</script>
<button class={classes} {onclick}>
{@render children()}
</button>Best Practices
Single Responsibility: Each component does one thing well
Prop Drilling Prevention: Use context for deeply nested data
Accessible by Default: Include ARIA attributes, keyboard support
Controlled vs Uncontrolled: Support both patterns when appropriate
Forward Refs: Allow parent access to DOM nodes
Memoization: Use
React.memo,useMemofor expensive rendersError Boundaries: Wrap components that may fail
Common Issues
Prop Explosion: Too many props - consider composition instead
Style Conflicts: Use scoped styles or CSS Modules
Re-render Cascades: Profile with React DevTools, memo appropriately
Accessibility Gaps: Test with screen readers and keyboard navigation
Bundle Size: Tree-shake unused component variants
Requirements and compatibility
Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta
“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.
Security
No issues found by our static scan· No issues found
A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.
Attribution and licence
- Created by
- Seth Hobson
- Publisher
- Seth Hobson (Community)
- Source
- wshobson/agents · plugins/ui-design/skills/web-component-design · commit 4bde316
- Licence
- MIT License (redistribution allowed)
- LICENSE (added by AutoGineer from LICENSE)
- ATTRIBUTION.md (written by AutoGineer)
- Synced
AutoGineer is not affiliated with or endorsed by Seth Hobson or Seth Hobson.
Download ZIP
The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download web-component-design.zip