From design-system-ops
Writes documentation for design system patterns—multi-component UI recipes covering use cases, anti-patterns, composition, and related patterns. For forms, data tables, etc.
npx claudepluginhub murphytrueman/design-system-opsThis skill uses the workspace's default tool permissions.
A skill for writing documentation for design system patterns. Patterns are distinct from components: a component is a discrete, reusable UI element; a pattern is a recurring solution composed from multiple components that addresses a specific user or product problem. Form validation, empty states, error handling, progressive disclosure — these are patterns.
Creates structured pattern library entries for UX design patterns with problem statements, solutions, anatomy, variants, behavior, examples, accessibility, and related patterns.
Writes usage guidelines for a specific named component covering when to use, when not to, edge cases, and anti-patterns. Useful for prescriptive guidance on single components.
Audits design systems for naming inconsistencies/hardcoded values, documents component variants/states/accessibility, extends with new tokens/patterns fitting existing system.
Share bugs, ideas, or general feedback.
A skill for writing documentation for design system patterns. Patterns are distinct from components: a component is a discrete, reusable UI element; a pattern is a recurring solution composed from multiple components that addresses a specific user or product problem. Form validation, empty states, error handling, progressive disclosure — these are patterns.
Pattern documentation is systematically underdone in most design systems. Teams document components in detail and leave patterns as implicit knowledge — accumulated through convention, absorbed during onboarding, and lost when people leave. The result is parallel local solutions that drift apart over time, and product teams that rebuild the same interaction in slightly different ways because no one wrote down the shared answer.
Good pattern documentation does two things. It explains the pattern clearly enough that a designer or developer encountering it for the first time can apply it correctly. And it explains the edges: when this pattern is not the right choice, what alternatives exist, and how to handle the cases that do not fit neatly.
Before documenting a pattern, confirm it is worth documenting. Not every recurring UI solution is a pattern — some are conventions, some are coincidences, and some are too specific to generalise.
A UI solution is a documentable pattern if:
A UI solution is NOT a documentable pattern if:
Where to find undocumented patterns:
Ask for or confirm:
If the pattern does not yet have a name, propose one before writing the documentation. Pattern names should describe the interaction or function, not the visual treatment: "confirmation dialog" not "modal with two buttons."
Category: [navigation / forms / feedback / layout / data display / other] Components used: [list the design system components this pattern draws on] Last updated: [date]
One to two sentences. Describe the pattern in terms of what it accomplishes for the user, not how it looks or which components it uses.
Example (form validation): Communicates the status of user input during and after form interaction, surfacing specific errors in the context where they occur so users can correct them without losing their progress.
Example (empty state): Guides users when a view has no content to display — whether because data does not exist yet, a search returned no results, or content was removed — and offers a clear path to the next action.
Describe the conditions under which this pattern is the right choice. Be specific about the context. Avoid "use this when you need to show an error" — that is not a usage condition, it is a circular definition.
Good format: "Use this pattern when [user or product situation]. It is appropriate when [specific conditions that make this the right choice over alternatives]."
Include the most important conditions, not an exhaustive list. Three to five is usually right.
As important as the above. Describe the conditions where a different pattern or approach is more appropriate.
For each exclusion, name the alternative: "If [condition], use [pattern or component name] instead."
This section prevents misapplication more than any amount of positive guidance.
Describe how the pattern is assembled from its component parts. This is not a code implementation guide — it is a structural description that works for designers and developers alike.
Cover:
If the pattern has multiple variants (e.g. an inline form validation and a summary form validation are both valid sub-patterns), document each variant's composition separately.
Document every state the pattern can be in. AI agents cannot build what they do not understand, and patterns fail most often at state boundaries — the transitions between states, not the states themselves.
For each state the pattern can occupy:
Common states to check for: default/resting, loading/pending, empty/no data, populated/active, error/invalid, success/complete, disabled/locked, partially complete.
If a state is not applicable, say so explicitly — "This pattern does not have an error state because [reason]." Silence is ambiguity. Ambiguity is drift.
Document the specific accessibility requirements for this pattern — not generic WCAG principles, but the specific keyboard behaviour, focus management, and screen reader experience that this pattern needs to implement.
Patterns often carry accessibility requirements that no individual component owns. A confirmation dialog pattern needs to manage focus on open, trap focus while open, and return focus on close — none of which a single component is responsible for, but the pattern as a whole must get right.
Cover:
Name the three to five most common ways this pattern is misapplied. Each anti-pattern should be specific to this pattern, not generic design advice. Write each as a one-sentence description of the misapplication, followed by one sentence on why it creates a problem.
If the pattern has visual examples available, a do/don't pairing is more effective than prose here. If not, write the anti-patterns as clearly as possible in text.
Cross-references to other patterns that are closely related, commonly confused with this one, or often used alongside it. For each:
If available: two to three named product contexts where this pattern is in use. This grounds the pattern in reality and gives teams a reference point for correct application.
If no production examples are available, note that and invite consuming teams to contribute examples after the documentation is published.
Before delivering the documentation, verify:
After publishing pattern documentation, note the expected impact and how to measure it:
If none of these signals improve within two quarters of publishing, the documentation may not be discoverable enough — review its placement and promotion.
ai-component-description skillIf the pattern involves a primary component that does not yet have an AI-optimised description, flag that. Pattern-level documentation and component-level AI descriptions work together: the pattern documentation explains the composition, and the AI description explains each component's contract within it.