home / skills / fusengine / agents / designing-systems

designing-systems skill

safe

/plugins/design-expert/skills/designing-systems

This skill helps you design scalable design systems using OKLCH colors, semantic CSS variables, and Tailwind v4 theming for consistent UX.

npx playbooks add skill fusengine/agents --skill designing-systems

Review the files below or copy the command above to add this skill to your agents.

Files (12)

SKILL.md

4.3 KB

---
name: designing-systems
description: Use when creating design systems, tokens, color palettes, typography scales, or theming. Covers OKLCH colors, CSS variables, Tailwind v4 @theme.
versions:
  tailwindcss: "4.1"
user-invocable: true
allowed-tools: Read, Write, Edit, Glob, Grep, Task
references: references/color-system.md, references/typography.md, references/theme-presets.md, references/grids-layout.md, references/ui-hierarchy.md, references/ui-spacing.md, references/ui-trends-2026.md, references/gradients-guide.md, references/tailwind-config.md, references/tailwind-utilities.md, references/tailwind-performance.md
related-skills: generating-components, theming-tokens, dark-light-modes
---

# Designing Systems

## Agent Workflow (MANDATORY)

Before ANY design system work, use `TeamCreate` to spawn 3 agents:

1. **fuse-ai-pilot:explore-codebase** - Find existing CSS variables, Tailwind config, colors
2. **fuse-ai-pilot:research-expert** - Verify latest OKLCH and Tailwind v4 patterns
3. **mcp__context7__query-docs** - Check Tailwind v4 @theme syntax

After implementation, run **fuse-ai-pilot:sniper** for validation.

---

## Overview

| Feature | Description |
|---------|-------------|
| **OKLCH Colors** | Wide gamut P3 color space |
| **CSS Variables** | Semantic token architecture |
| **Tailwind v4 @theme** | CSS-first configuration |
| **60-30-10 Rule** | Color distribution ratio |

---

## Critical Rules

1. **OKLCH only** - No hex or RGB for colors
2. **Forbidden fonts** - Inter, Roboto, Arial are BANNED
3. **CSS variables** - Never hard-code colors
4. **Analyze first** - Document existing system before changes
5. **Dark mode** - Always define both light and dark tokens

---

## Architecture

```
styles/
├── tokens/
│   ├── colors.css       (~50 lines)
│   ├── typography.css   (~30 lines)
│   └── spacing.css      (~20 lines)
└── app.css              (~40 lines - @import + @theme)
```

→ See [color-system.md](references/color-system.md) for token examples

---

## Reference Guide

### Concepts

| Topic | Reference | When to Consult |
|-------|-----------|-----------------|
| **Colors** | [color-system.md](references/color-system.md) | OKLCH palettes, psychology |
| **Typography** | [typography.md](references/typography.md) | Fonts, scale, mobile sizes |
| **Theme Presets** | [theme-presets.md](references/theme-presets.md) | Brutalist, Solarpunk, etc. |
| **Grids** | [grids-layout.md](references/grids-layout.md) | 12-column, spacing |
| **UI Hierarchy** | [ui-hierarchy.md](references/ui-hierarchy.md) | Visual hierarchy patterns |
| **UI Spacing** | [ui-spacing.md](references/ui-spacing.md) | Spacing systems |
| **UI Trends** | [ui-trends-2026.md](references/ui-trends-2026.md) | 2026 design trends |
| **Gradients** | [gradients-guide.md](references/gradients-guide.md) | Gradient patterns |
| **Tailwind Config** | [tailwind-config.md](references/tailwind-config.md) | v4 @theme setup |
| **Tailwind Utils** | [tailwind-utilities.md](references/tailwind-utilities.md) | Utility patterns |
| **Tailwind Perf** | [tailwind-performance.md](references/tailwind-performance.md) | Performance tips |

### Templates

Templates are in generating-components skill for implementation examples.

---

## Quick Reference

### OKLCH Color Token

```css
:root {
  --color-primary: oklch(55% 0.20 260);
  --color-primary-foreground: oklch(98% 0.01 260);
}

.dark {
  --color-primary: oklch(65% 0.20 260);
}
```

→ See [color-system.md](references/color-system.md) for full palette

### Typography Scale

```css
--font-display: 'Clash Display', sans-serif;
--font-sans: 'Satoshi', sans-serif;
--font-mono: 'JetBrains Mono', monospace;
```

→ See [typography.md](references/typography.md) for approved fonts

### Tailwind v4 @theme

```css
@import "tailwindcss";

@theme {
  --color-primary: var(--color-primary);
  --font-display: var(--font-display);
}
```

→ See [tailwind-best-practices.md](references/tailwind-best-practices.md) for config

---

## Best Practices

### DO
- Use OKLCH for wide gamut colors
- Define semantic tokens (primary, success, destructive)
- Support dark mode from the start
- Follow 60-30-10 color distribution
- Use approved fonts only

### DON'T
- Hard-code hex/RGB colors
- Use Inter, Roboto, Arial fonts
- Skip dark mode variables
- Create tokens without semantic meaning
- Mix color spaces (stick to OKLCH)

Overview

This skill guides creation of robust design systems: color tokens, typography scales, spacing, and Tailwind v4 theming. It enforces OKLCH color usage, semantic CSS variables, dark-mode parity, and a CSS-first @theme workflow for predictable theming. Use it to standardize visual systems and prevent mixed color spaces or banned fonts.

How this skill works

Before any implementation, spawn three agents to map the codebase and verify standards: one to scan existing CSS variables and Tailwind config, one to confirm OKLCH and Tailwind v4 patterns, and one to validate @theme syntax. The skill prescribes token files (colors, typography, spacing) and a single app entry that imports tokens and applies @theme. After changes, run an automated validation agent to check tokens, dark mode parity, and forbidden assets.

When to use it

When building or refactoring a design system across a codebase
When migrating color tokens to OKLCH for wide-gamut support
When adopting Tailwind v4 with a CSS-first @theme setup
When introducing semantic tokens for theming and dark mode
When enforcing font and token usage rules across teams

Best practices

Always analyze the existing system first—document variables and Tailwind config
Use OKLCH exclusively for color tokens; never hard-code hex or RGB
Define semantic tokens (e.g., --color-primary, --color-success) and avoid presentational names
Create light and dark token sets in tandem; maintain parity for each token
Keep tokens in dedicated files (colors.css, typography.css, spacing.css) and import from a single app stylesheet
Ban specified fonts and use only approved typefaces from the typography palette

Example use cases

Convert an existing hex-based palette to OKLCH tokens and update components to use CSS variables
Set up Tailwind v4 @theme to map CSS tokens into utility classes for consistent theming
Design a typography scale and token file, then wire fonts into the @theme block
Implement 60-30-10 color distribution for a new product theme with dark-mode counterparts
Run the validation agent after a release to ensure no forbidden fonts or hard-coded colors were introduced

FAQ

Why enforce OKLCH instead of hex or RGB?

OKLCH provides perceptually uniform adjustments and better wide-gamut support, making color transforms and accessible contrasts more reliable.

What if components still reference hex values?

First, document occurrences via the scan agent, then replace hard-coded values with semantic CSS variables and re-run validation to confirm compliance.