aesthetic-guide
Scannednpx machina-cli add skill petekp/claude-code-setup/aesthetic-guide --openclawAesthetic Guide
Produce exhaustive, implementation-ready design system documentation for a named UI aesthetic. The output is a reference guide detailed enough that a coding agent can faithfully implement the aesthetic with minimal room for interpretation.
Workflow
- Identify the aesthetic from the user's request
- Check the catalog — read references/aesthetic-catalog.md to see if pre-researched data exists for this aesthetic
- Research if needed — if the aesthetic is not in the catalog or the user wants a custom variant, conduct web research to gather implementation-level specifics (exact CSS values, fonts, colors, timing functions)
- Load the output schema — read references/output-schema.md for the required structure
- Generate the guide — fill every section of the output schema with concrete, copy-pasteable values. No hand-waving, no "choose an appropriate value" — every property must have an exact value or a constrained range with rationale.
- Deliver as a markdown file — write the completed guide to the project (default:
.claude/docs/{aesthetic-name}-design-system.md)
Research Protocol
When researching an aesthetic not in the catalog:
- Search for "{aesthetic} CSS", "{aesthetic} UI design system", "{aesthetic} web design examples"
- Look for open-source implementations, CodePen examples, design system documentation
- Extract concrete values: hex codes, font names, px/rem values, cubic-bezier curves, shadow syntax
- Cross-reference multiple sources to identify the consensus properties that define the aesthetic
- Distinguish between essential properties (without these, it's not the aesthetic) and characteristic properties (common but optional)
Output Requirements
- Every color must be a hex or HSL value, never a name like "dark blue"
- Every font must be a specific family with fallback stack
- Every spacing value must be in px or rem
- Every transition must have duration + timing function
- Every interactive state (hover, active, focus, disabled) must have explicit CSS
- Every component must have all pseudo-states defined
- Include both CSS custom properties (variables) and Tailwind equivalents where applicable
Customization
The user may request:
- A specific framework (Tailwind, vanilla CSS, CSS-in-JS) — adjust output format
- A hybrid ("brutalist with soft shadows") — blend aesthetics, noting which properties come from which
- A variant ("dark mode cyberpunk" vs "light mode cyberpunk") — generate the specific variant
- Partial guide (just colors, just typography) — generate only the requested sections
Source
git clone https://github.com/petekp/claude-code-setup/blob/main/skills/aesthetic-guide/SKILL.mdView on GitHub Overview
Aesthetic-guide researches a named UI design aesthetic (e.g., brutalist, glassmorphism, retro-futuristic, Swiss modernist, Apple HIG, neumorphism, minimalism, cyberpunk, Material Design, art deco, vaporwave, etc.) and outputs a complete, implementation-ready design system. It delivers exact CSS values, color palettes, typography stacks, component states, and animations so a coding agent can faithfully reproduce the style with zero ambiguity.
How This Skill Works
The tool identifies the requested aesthetic, consults a catalog for pre-researched data, and conducts targeted web research if needed to collect exact values. It then loads the required output schema and generates every section with concrete values, including CSS variables, font stacks, spacing scales, color ramps, and timing functions. Finally, it exports a markdown design-system doc or a format suitable for your repo.
When to Use It
- You name a specific UI aesthetic and need a complete, copy-paste-ready style guide with exact CSS values.
- You’re producing a dark-mode or variant version of an existing aesthetic and require precise tokens.
- You want framework-ready outputs (vanilla CSS, Tailwind, or CSS-in-JS) with explicit equivalents.
- You’re building or updating a design system repository and need exhaustive documentation per aesthetic.
- You need to validate or compare multiple aesthetics, ensuring there’s no ambiguity in typography, colors, and motion.
Quick Start
- Step 1: Tell Aesthetic-guide which named aesthetic to implement (e.g., 'glassmorphism' or 'neumorphism').
- Step 2: Specify output format and variant (e.g., vanilla CSS, Tailwind, dark mode).
- Step 3: Run the generator and paste the produced design-system doc into your repo.
Best Practices
- Start by pinning a single source of truth for the aesthetic (color tokens, typography, spacing).
- Define all component states (default, hover, focus, active, disabled) with explicit values.
- Include both CSS custom properties and Tailwind equivalents where applicable.
- Separate essential properties (must-have) from characteristic properties (optional) and document rationale.
- Cross-check values against accessibility guidelines (contrast ratios, focus outlines, motion duration limits).
Example Use Cases
- Brutalist admin dashboard: bold typography, dense grids, high-contrast color ramps.
- Glassmorphism landing page: translucent cards, soft shadows, pastel accents.
- Cyberpunk control panel: neon accents on dark backgrounds with jittery micro-interactions.
- Swiss modernist editor: clean grids, neutral palette, tight typography, generous white space.
- Minimalist product app: restrained palette, generous typography, subtle motion.
