Comprehensive workflow for building a design system from initial audit through design tokens, component library creation, documentation, and organizational adoption.
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.
A design system is the single source of truth for your organization's visual language and UI components. It reduces duplication, enforces consistency, improves accessibility, and accelerates development by providing pre-built, tested, documented components. This workflow takes you from a UI audit through design token definition, component development, documentation, and the hardest part: organizational adoption.
The workflow is structured to deliver value incrementally. You will start by auditing what exists, define the foundational tokens, build a small set of core components, document them thoroughly, and then expand based on adoption feedback. A design system that nobody uses is worse than no design system at all -- so adoption strategy is woven throughout.
Comprehensive workflow for building a design system from initial audit through design tokens, component library creation, documentation, and organizational adoption.
How much does it cost?+
Nothing. It ships with Murage, which is open source. Your bots run on the AI plan you already have.
Can I change it?+
Yes. Open it in Settings → Skills to read, edit or duplicate it. Skill Guard scans it again after every edit.
Give your first job to Murage.
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.
evaluate the current state of your UI. Conduct a visual audit: screenshot every unique button, form element, color, typography style, spacing value, and icon across all products. Catalog the inconsistencies. Run an accessibility audit (WCAG 2.2 Level AA) to identify violations that the design system must address. This audit becomes your "before" baseline and prioritization input.
Input: Existing product(s) with their UI, Any existing style guides or brand guidelines, Known accessibility issues
Output: Visual inventory: catalog of every unique UI pattern in use, Inconsistency report (e.g., "17 different button styles found"), Accessibility audit report with WCAG violations
Key focus: Use the Accessibility Auditor skill to evaluate the current state of your UI
Step 2: Define Design Tokens (uses: css-master)
define your design token architecture: the atomic values (colors, spacing, typography, shadows, borders, breakpoints) that every component will reference. Use the Tailwind Designer skill if you are using Tailwind to map tokens to a custom theme configuration. Design tokens in three tiers: global (raw values), semantic (purpose-based aliases), and component (component-specific supersedes). Ensure tokens support dark mode and high-contrast themes from the start.
Input: Brand guidelines (colors, typography, spacing), Audit results from Step 1, Multi-theme requirements (dark mode, high contrast)
Output: Design token specification (JSON/YAML format), Color palette with semantic aliases (primary, secondary, success, error, etc.), Typography scale (font families, sizes, weights, line heights)
Key focus: Use the CSS Master skill to define your design token architecture: the atomic values (colors, spacing, typography, shadows, borders, breakpoints) that every component will reference
design component APIs that are composable, accessible, and flexible. Use the React Architect skill (or equivalent for your framework) to implement the components with proper TypeScript types, ref forwarding, and polymorphic props (as/component pattern). Start with the 8-12 foundational components: Button, Input, Select, Checkbox, Radio, TextArea, Card, Modal, Toast, Badge, Avatar, and Spinner. Each component must be fully accessible by default (keyboard navigation, ARIA attributes, focus management).
Input: Design tokens from Step 2, Prioritized component list from Step 1, Framework choice (React, Vue, etc.)
Output: 8-12 core components with full TypeScript types, Component API documentation (props, variants, sizes), Accessibility implementation (ARIA, keyboard nav, focus management)
Key focus: Use the Component Library skill to design component APIs that are composable, accessible, and flexible
Step 4: Test Components Thoroughly (uses: unit-test-writer)
write unit tests for component behavior (interactions, state changes, prop variations). Use the Visual Regression skill to set up visual regression testing that catches unintended visual changes. Re-run the Accessibility Auditor skill to verify every component meets WCAG 2.2 Level AA. Test across supported browsers and devices. The test suite must be fast enough to run in CI on every PR.
Input: Components from Step 3, Visual design specifications, Browser/device support requirements
Output: Unit test suite (behavior and interaction tests), Visual regression test baseline screenshots, Accessibility test suite (automated axe-core + manual checklist)
Key focus: Use the Unit Test Writer skill to write unit tests for component behavior (interactions, state changes, prop variations)
Step 5: Build Documentation Site (uses: docs-site-builder)
create a documentation site that serves as the design system's home. Include: live component playground (interactive props), copy-pasteable code examples, design token reference, accessibility guidelines, getting started guide, contribution guide, and migration guide from old patterns. The docs site is the design system's marketing material -- it must be excellent.
Input: Components from Step 3, Design tokens from Step 2, Target audience (designers, developers, product managers)
Output: Documentation site with live component playground, Getting started guide (install, configure, use first component), Component API reference with interactive examples
Key focus: Use the Docs Site Builder skill to create a documentation site that serves as the design system's home
Step 6: Establish Versioning and Release Process (uses: changelog-writer)
establish a versioning and release process. Follow semantic versioning strictly: patch for bug fixes, minor for new features and new components, major for breaking API changes. Automate changelog generation from conventional commits. Set up a release pipeline that publishes to your package registry (npm, internal registry). Create a deprecation policy: components and props get deprecated warnings for at least one major version before removal.
Key focus: Use the Changelog Writer skill to establish a versioning and release process
Step 7: Drive Adoption (uses: component-library)
develop an adoption strategy. Start with one willing team as a pilot. Help them migrate their most-used components and measure the reduction in CSS and custom component code. Create codemods or migration scripts for common patterns. Track adoption metrics: percentage of UI using design system components, number of custom components replaced, and developer satisfaction scores. Address resistance by showing time savings and quality improvements.
Input: Published design system package, Product teams as consumers, Existing component usage in products
Output: Adoption metrics dashboard, Migration scripts/codemods for common patterns, Pilot team case study with measured improvements
Key focus: Use the Component Library skill to develop an adoption strategy
Decision Points
After Step ?:
If After Step 1: Expand audit scope to cover missed surfaces
If After Step 3: Fix accessibility issues before testing and docs
If After Step 5: Improve docs until a developer can self-serve
If After Step 7 (pilot): Address pilot team feedback before wider rollout
Failure Handling
Building too many components too fast: -- Start with 8-12 core components and prove adoption before expanding. Unused components are wasted effort.
Designing in isolation: -- A design system built without consumer input will not match consumer needs. Co-design with product teams.
Accessibility as an afterthought: -- Retrofitting accessibility is expensive. Build it in from the first component.
No adoption strategy: -- "Build it and they will come" does not work. Actively drive adoption with migration support, codemods, and measurement.
Token inconsistency: -- If tokens are not used consistently, the design system's visual consistency breaks. Lint for direct color/spacing values.
Expected Outcome
When this workflow is complete, the user will have:
Design system covers 80%+ of UI patterns across products
New features are built with design system components by default
Accessibility compliance improves measurably across all products
Developer velocity increases (measured by reduced CSS and custom component code)
Visual consistency score improves (measured by reduced unique design patterns)
Design system documentation has high satisfaction scores (> 4/5)