design-system-patterns

Overview of design-system-patterns skill

The design-system-patterns skill helps an AI agent design the foundation of a scalable UI system: token structure, theming architecture, and component API patterns. It is best for teams creating or refactoring a design system, building a component library, adding light/dark or multi-brand theming, or trying to standardize design decisions across products.

What the design-system-patterns skill is best at

This skill is strongest when you need architecture, not just isolated snippets. It gives the agent a structured way to reason about:

• token layers such as primitive, semantic, and component tokens
• CSS custom property strategies for themes
• component patterns like variants, polymorphism, and compound components
• design-system decisions that must scale across many components

Real job-to-be-done

Most users do not need “a design system” in the abstract. They need a practical plan for questions like:

• How should we name and organize tokens?
• How do we support dark mode without rewriting every component?
• What component API patterns will stay maintainable as the library grows?
• How do we avoid hard-coded styling choices spreading through the codebase?

The design-system-patterns skill is useful because it frames those decisions as system design work instead of one-off styling tasks.

Who should install this skill

Good fit:

• frontend engineers building shared UI infrastructure
• design system teams defining token and theming conventions
• React teams building reusable component libraries
• teams aligning design tooling with implementation patterns

Less ideal fit:

• one-off page styling
• quick visual mockups with no reusable system
• highly framework-specific implementation work where you already know the exact pattern you want

What differentiates this skill from a generic prompt

A generic prompt can suggest “use design tokens” or “add dark mode.” The design-system-patterns skill is more useful when you want the agent to work from established design-system layers and architecture patterns. The included references go deeper on token taxonomy, theming with CSS variables, and component composition patterns, which makes outputs more coherent and reusable.

Files that matter before you commit to it

Read these first to judge fit:

• SKILL.md
• references/design-tokens.md
• references/theming-architecture.md
• references/component-architecture.md

If those topics match your immediate problem, this skill is likely worth installing.

How to Use design-system-patterns skill

design-system-patterns install context

The repository does not expose a custom package install just for this skill; it lives inside the wshobson/agents repository. In a skills-compatible environment, install from the repo and target the design-system-patterns skill:

npx skills add https://github.com/wshobson/agents --skill design-system-patterns

If your agent runtime uses a different skill-loading flow, use the repo URL and skill slug from:

plugins/ui-design/skills/design-system-patterns

What input the skill needs from you

The design-system-patterns usage quality depends heavily on how concrete your system constraints are. Provide:

• platform scope: web only, React, mobile, or multi-platform
• theming scope: light/dark, multi-brand, high contrast, reduced motion
• token scope: colors only, full foundation, or component tokens too
• component scope: greenfield library, migration, or refactor
• constraints: CSS Modules, Tailwind, CSS-in-JS, SSR, legacy styles, design tooling
• target outputs: token schema, theme contract, component API examples, migration plan

Without this context, the agent will usually return generic design-system advice.

Turn a rough goal into a strong prompt

Weak prompt:

Help me build a design system.

Better prompt:

Use the design-system-patterns skill to propose a token hierarchy and theming architecture for a React component library. We need light/dark themes, semantic color tokens, and scalable button/card/input APIs. We currently use CSS custom properties and want to avoid hard-coded colors in components. Show naming conventions, file organization, and example component variant patterns.

This works better because it gives the agent a scope, implementation direction, and definition of success.

Best workflow for design-system-patterns usage

A practical workflow:

1. Ask for the architecture first, not code generation first.
2. Validate token layers and theme model.
3. Ask for component API patterns that consume those tokens.
4. Then request example implementations for 1 to 3 representative components.
5. Finally, ask for migration steps and guardrails.

This order matters. If you start with component code, the agent may lock in ad hoc decisions before the token system is clear.

Read these repository files in order

For the fastest understanding path:

1. SKILL.md for scope
2. references/design-tokens.md for token structure
3. references/theming-architecture.md for CSS variable and theme setup
4. references/component-architecture.md for reusable component patterns

That reading order mirrors the implementation order most teams should follow: tokens, themes, then components.

What the design-tokens reference is especially useful for

Use references/design-tokens.md when you need the agent to separate:

• primitive tokens like raw palette values
• semantic tokens like text/background/surface roles
• component tokens for local component decisions

This is one of the most adoption-relevant parts of the design-system-patterns guide, because many teams fail by jumping straight from palette values to component code.

What the theming reference helps you decide

Use references/theming-architecture.md to shape prompts around:

• CSS custom property contracts
• theme switching with [data-theme]
• system preference detection
• persistent theme choice
• accessibility-related modes such as reduced motion and high contrast

If your real goal is theme architecture rather than component APIs, point the agent there explicitly.

What the component architecture reference covers well

Use references/component-architecture.md when asking for:

• compound components
• variant and size APIs
• polymorphic as patterns
• context-based component composition

This matters if you are building a reusable library and want APIs that scale beyond one component family.

A high-quality prompt template

Use this structure for design-system-patterns for Design Systems work:

• product and platform
• current styling approach
• theming requirements
• token categories needed
• first components to standardize
• accessibility constraints
• expected deliverable format

Example:

Use the design-system-patterns skill. We are building a React web design system for two brands with light/dark themes. Current stack: CSS custom properties plus TypeScript. We need primitive and semantic tokens first, then component tokens for button, input, and card. Recommend naming conventions, theme variable structure, component variant patterns, and a migration plan from hard-coded styles.

Practical tips that improve output quality

Ask the agent to produce specific artifacts, such as:

• token naming matrix
• theme variable contract
• component API table
• folder structure
• migration checklist
• risks and tradeoffs

Those outputs are much easier to review than broad narrative advice.

Common adoption blockers to address up front

Before relying on the skill, tell the agent about:

• whether design already has a token source of truth
• whether you need output consumable by multiple platforms
• whether your components must support SSR
• whether accessibility modes are required from day one
• whether you need backwards-compatible migration

These constraints materially change the architecture the skill should suggest.

design-system-patterns skill FAQ

Is the design-system-patterns skill good for beginners?

Yes, if you already understand basic UI styling and component development. The references are structured enough to help intermediate teams make better system decisions. Absolute beginners may still need separate guidance on CSS, React, or accessibility basics.

When should I use design-system-patterns instead of a normal prompt?

Use design-system-patterns when the task involves system-level consistency: token hierarchy, theming, or reusable component architecture. For a single component style tweak or one-off UI bug, a normal prompt is usually faster.

Does this skill generate production-ready code?

It is better treated as an architecture and pattern skill than a drop-in implementation generator. It can help produce example code, but the real value is in making token, theme, and component decisions more coherent before large-scale implementation begins.

Is the design-system-patterns skill tied to React only?

No, but some reference patterns, especially compound and polymorphic component examples, are React-oriented. The token and theming guidance is broadly useful even if your implementation layer differs.

Does it help with multi-brand theming?

Yes. This is one of the clearest fit cases for the design-system-patterns skill, especially when combined with semantic tokens and CSS custom property contracts.

When is this skill the wrong choice?

Skip it if you need:

• visual design exploration rather than implementation architecture
• framework-specific low-level styling fixes
• a tiny app with no shared component system
• purely marketing-site styling with little reuse

What is the biggest limitation?

The skill gives patterns, not repository-specific enforcement. It does not include scripts, rules, or generators in this skill folder, so quality depends on how clearly you provide your constraints and how well you adapt the patterns to your stack.

How to Improve design-system-patterns skill

Start with architecture decisions, not component requests

The fastest way to get weak results from design-system-patterns is to ask for Button code before defining token layers and theme semantics. Ask first for the system model, then for implementation examples.

Provide a token strategy brief

Strong inputs include decisions or open questions about:

• primitive vs semantic token separation
• naming conventions
• aliasing rules
• which values can vary by theme
• which values must remain stable across brands

This helps the agent avoid mixing raw values with semantic roles.

Specify your theming model explicitly

Say whether you need:

• light/dark only
• brand themes plus color modes
• OS preference detection
• user preference persistence
• accessibility modes

The theming architecture can become overbuilt or underbuilt if you leave this vague.

Use representative components for iteration

Do not test the skill on only one trivial component. Ask it to model a small set such as:

• Button for variants and states
• Input for form semantics
• Card for surfaces and elevation

That mix reveals whether the proposed token system and component API can actually scale.

Ask for tradeoffs, not just recommendations

A strong follow-up prompt is:

Using the design-system-patterns skill, compare two token naming approaches and explain migration, readability, and long-term maintenance tradeoffs.

This improves decision quality more than asking for a single “best” structure.

Correct common failure modes early

Watch for these problems in first-pass outputs:

• semantic tokens that are too close to raw palette names
• component APIs that expose too many styling internals
• dark mode added as overrides instead of a token contract
• component examples that hard-code values instead of consuming tokens
• patterns that ignore accessibility modes

When you see one, ask the agent to revise that layer specifically rather than regenerating everything.

Ask for artifacts you can review with design and engineering

To improve the design-system-patterns guide output, request deliverables that survive team review:

• token JSON examples
• CSS variable contract examples
• component prop API tables
• migration phase plan
• naming rules with examples and anti-examples

These are easier to debate and adopt than abstract recommendations.

Iterate from your real repository constraints

The best second prompt usually includes actual constraints from your codebase, such as:

• existing token files
• current CSS variable names
• component prop inconsistencies
• theming bugs
• brand requirements

The design-system-patterns skill becomes much more valuable when it is asked to transform a messy real system rather than describe an ideal one.