skills/pbakaus_impeccable
1
0
Fork 0
mirror of https://github.com/pbakaus/impeccable.git synced 2026-09-12 06:06:37 +03:00
Code Issues Packages Projects Releases Wiki Activity

Update README to reflect current architecture

Browse Source 
- Clarify: 1 skill with 7 reference files (not 8 separate skills)
- Add "The Problem" section about AI design bias
- Simplify installation and usage sections
- Add patterns/anti-patterns summary
- Add author credit

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Paul Bakaus
2025-12-16 17:48:10 -08:00
co-authored by Claude Opus 4.5
parent e99828bfdf
commit de0bebbcec
1 changed files with 62 additions and 226 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+62 -226
View File
@@ -1,306 +1,142 @@
# impeccable.style
Cross-provider design skills and commands for LLM-powered development tools.
The anti-slop framework for AI design. One skill and 15 commands that fight model bias and produce intentional, distinctive frontends.
> **🌐 Visit [impeccable.style](https://impeccable.style)** to download bundles, individual skills, or commands for your IDE/CLI.
> **Visit [impeccable.style](https://impeccable.style)** to download bundles for Cursor, Claude Code, Gemini CLI, or Codex CLI.
## Quick Start
## The Problem
**Option 1: Download from Website (Recommended)**
Visit [impeccable.style](https://impeccable.style) and download the complete bundle for your tool:
- One-click ZIP downloads for Cursor, Claude Code, Gemini CLI, or Codex CLI
- Individual skill and command downloads
- Always up-to-date with the latest version
**Option 2: Clone from GitHub**
```bash
git clone https://github.com/pbakaus/vibe-design-plugins.git
cd vibe-design-plugins
```
Then copy the appropriate files from `dist/` to your IDE/CLI configuration directory (see [Installation](#installation) below).
Every LLM learned from the same generic templates. Without guidance, you get the same predictable mistakes: Inter font, purple gradients, cards nested in cards, gray text on colored backgrounds. This framework fights that bias.
## What's Included
### The Skill: frontend-design
A comprehensive design skill that guides creation of distinctive, production-grade frontend interfaces. Includes 7 domain-specific reference files:
- **typography** - Type systems, font selection, modular scales, fluid type, OpenType features
- **color-and-contrast** - OKLCH color spaces, tinted neutrals, dark mode, accessibility
- **spatial-design** - Spacing systems, grids, visual hierarchy, container queries
- **motion-design** - Easing curves, perceived performance, reduced motion, staggering
- **interaction-design** - Form design, focus states, loading patterns, keyboard navigation
- **responsive-design** - Mobile-first, fluid design, input detection, safe areas
- **ux-writing** - Button labels, error messages, empty states, accessibility
### Commands (15)
**Core Workflow:**
- **normalize** - Align features with design system standards
- **audit** - Comprehensive quality audit with severity ratings and recommendations
| Command | Purpose |
|---------|---------|
| **normalize** | Align with design system standards |
| **audit** | Quality audit with severity ratings |
| **polish** | Final pass before shipping |
| **clarify** | Improve unclear UX copy |
| **optimize** | Performance improvements |
| **harden** | Error handling, i18n, edge cases |
| **quieter** | Tone down overly bold designs |
| **bolder** | Amplify boring designs |
| **simplify** | Strip to essence |
| **animate** | Add purposeful motion |
| **colorize** | Introduce strategic color |
| **delight** | Add moments of joy |
| **extract** | Pull into design system |
| **adapt** | Adapt for different devices |
| **onboard** | Design onboarding flows |
**Quality & Polish:**
- **polish** - Final quality pass before shipping (alignment, spacing, consistency)
- **clarify** - Improve unclear UX copy and microcopy
- **optimize** - Performance improvements (loading, rendering, bundle size)
- **harden** - Error handling, i18n, text wrapping, edge cases
### Patterns & Anti-Patterns
**Aesthetic Adjustment:**
- **quieter** - Tone down overly bold designs → refined sophistication
- **bolder** - Amplify boring designs → memorable impact
- **simplify** - Strip to essence → clarity through reduction
The skill includes curated patterns that fight model bias:
**Enhancement:**
- **animate** - Add purposeful motion and micro-interactions
- **colorize** - Introduce strategic color to monochromatic designs
- **delight** - Add moments of joy and personality
**Do**: Use modular type scales, pair distinctive fonts, use off-whites and near-blacks, create visual rhythm through varied spacing, use asymmetry and unexpected compositions.
**System & Growth:**
- **extract** - Pull components/tokens into design system
- **adapt** - Adapt designs for different devices/contexts
- **onboard** - Design onboarding flows and empty states
### Skills (8)
- **frontend-design** - Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics.
- **typography** - Master typography systems that balance timeless principles with modern web capabilities. Creates readable, systematically coherent typography that is both performant and aesthetically distinctive.
- **color-and-contrast** - Build sophisticated color systems balancing aesthetics with accessibility and function. Produces beautiful, accessible color implementations with systematic coherence across all theme variants.
- **spatial-design** - Master spatial design balancing systematic precision with artistic composition. Creates systematically organized layouts with compelling visual hierarchy and intentional spatial relationships.
- **motion-design** - Create purposeful motion that enhances usability and provides feedback without sacrificing performance. Produces smooth, delightful animations that guide attention and reinforce interactions while maintaining 60fps performance.
- **interaction-design** - Design intuitive interaction patterns that feel natural and provide clear feedback. Creates accessible, forgiving interfaces where every state is clear and every action provides immediate feedback.
- **responsive-design** - Create responsive interfaces that adapt beautifully across devices, screen sizes, and input methods. Produces fluid, performant experiences that feel native to each device while maintaining consistency.
- **ux-writing** - Write clear, helpful, and human interface copy that users understand immediately. Produces concise, empathetic copy that guides users confidently through tasks without confusion or frustration.
## Command & Skill Relationships
### Diagnostic Flow
1. **audit** (report issues) → Use specific commands to fix:
- Design system issues → **normalize** or **extract**
- Performance issues → **optimize**
- Edge cases → **harden**
- Responsiveness → **adapt**
- Copy clarity → **clarify**
### Aesthetic Direction Flow
- Too boring → **bolder** + **colorize** + **delight**
- Too intense → **quieter** + **simplify**
- Too cluttered → **simplify** + **normalize**
- Too static → **animate** + **delight**
### Production Flow
1. **Build** → Use skills (**frontend-design**, **typography**, **spatial-design**, etc.)
2. **Refine** → **normalize** + **clarify** + **adapt**
3. **Harden** → **harden** + **optimize**
4. **Audit** → **audit** to catch issues
5. **Polish** → **polish** final pass
6. **Enhance** → **delight** + **animate** (optional)
### Skills Support Commands
- **typography** skill → **normalize** typography across app
- **ux-writing** skill → **clarify** existing copy
- **responsive-design** skill → **adapt** for new device
- **motion-design** skill → **animate** static interface
**Don't**: Use overused fonts (Arial, Inter), use gray text on colored backgrounds, use pure black/gray (always tint), wrap everything in cards, nest cards inside cards, use bounce/elastic easing.
## Installation
After downloading from [impeccable.style](https://impeccable.style) or cloning this repo, install for your provider:
### Cursor
**From Website**: Download the Cursor bundle ZIP from [impeccable.style](https://impeccable.style) and extract directly into your project:
```bash
# Extract the ZIP directly into your project root
# The ZIP contains a .cursor/ folder ready to use
# From website ZIP
unzip impeccable-style-cursor.zip -d your-project/
```
**From Repo**: Copy directly from the dist directory:
```bash
# From repo
cp -r dist/cursor/.cursor .cursor/
```
**Note**: Cursor doesn't support command arguments or frontmatter, so commands work but with simplified functionality.
**Reference**:
- [Cursor Commands Documentation](https://cursor.com/docs/agent/chat/commands)
- [Cursor Rules Documentation](https://cursor.com/docs/context/rules)
### Claude Code
**From Website**: Download the Claude Code bundle ZIP from [impeccable.style](https://impeccable.style) and extract:
```bash
# Global installation
unzip impeccable-style-claude-code.zip
cp -r .claude/* ~/.claude/
# Or project-specific
unzip impeccable-style-claude-code.zip -d your-project/
```
**From Repo**:
```bash
# Global installation
# Global
cp -r dist/claude-code/.claude/* ~/.claude/
# Or project-specific
# Project-specific
cp -r dist/claude-code/.claude .claude/
```
**Reference**:
- [Claude Code Slash Commands](https://code.claude.com/docs/en/slash-commands)
- [Anthropic Skills Documentation](https://github.com/anthropics/skills)
### Gemini CLI
**From Website**: Download the Gemini CLI bundle ZIP from [impeccable.style](https://impeccable.style) and extract:
```bash
# Extract and install
unzip impeccable-style-gemini.zip
# Commands (global)
cp -r .gemini/* ~/.gemini/
# Skills (project-specific)
cp GEMINI*.md ~/your-project-root/
```
**From Repo**:
```bash
cp -r dist/gemini/.gemini/* ~/.gemini/
cp dist/gemini/GEMINI*.md ~/your-project-root/
```
**Note**:
- Commands use `.toml` format with `{{args}}` placeholders
- `GEMINI.md` uses `@file.md` import syntax to load modular skill files
- Skills should be placed at your project root for project-specific context
- For global skills, place `GEMINI.md` in `~/.gemini/`
**Reference**:
- [Gemini CLI Custom Slash Commands](https://cloud.google.com/blog/topics/developers-practitioners/gemini-cli-custom-slash-commands)
- [Gemini CLI Skills (GEMINI.md)](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/gemini-md.md)
### Codex CLI
**From Website**: Download the Codex CLI bundle ZIP from [impeccable.style](https://impeccable.style) and extract:
```bash
# Extract and install
unzip impeccable-style-codex.zip
# Prompts (global)
cp -r .codex/* ~/.codex/
# Skills (project-specific)
cp AGENTS*.md ~/your-project-root/
```
**From Repo**:
```bash
cp -r dist/codex/.codex/* ~/.codex/
cp dist/codex/AGENTS*.md ~/your-project-root/
```
**Note**:
- Commands are invoked as `/prompts:<name>` (e.g., `/prompts:normalize`)
- The `AGENTS.md` file guides Codex to read modular skill files as needed
- Place `AGENTS.md` at your repository root
**Reference**:
- [Codex CLI Slash Commands](https://developers.openai.com/codex/guides/slash-commands#create-your-own-slash-commands-with-custom-prompts)
- [Codex CLI Skills (AGENTS.md)](https://developers.openai.com/codex/guides/agents-md)
## Usage
### Commands
**Cursor, Claude Code**:
**Cursor, Claude Code:**
```
/normalize
/audit
/polish
```
**Gemini**:
**Gemini:**
```
/normalize <optional-feature-name>
/normalize <optional-feature>
/audit <optional-area>
```
**Codex**:
**Codex:**
```
/prompts:normalize
/prompts:normalize FEATURE="dashboard"
/prompts:audit
```
### Skills
Skills are automatically available once installed. Refer to your provider's documentation for how skills are activated:
- **Cursor**: Rules apply automatically to the context
- **Claude Code**: Skills activated via `/skills` or `@skill-name`
- **Gemini**: Gemini reads `GEMINI.md` and automatically imports referenced skill files using `@file.md` syntax
- **Codex**: Codex reads `AGENTS.md` and automatically loads referenced skill files when needed
## Provider Comparison
| Feature | Cursor | Claude Code | Gemini CLI | Codex CLI |
|---------|---------|-------------|------------|-----------|
| Command Args | ❌ | ✅ | ✅ | ✅ |
| Frontmatter | ❌ | ✅ | ✅ (TOML) | ✅ |
| Modular Skills | ❌ | ❌ | ✅ | ✅ |
## Development
### Local Setup
```bash
# Clone the repo
git clone https://github.com/pbakaus/vibe-design-plugins.git
cd vibe-design-plugins
# Build distribution files
bun run build
# Start dev server
bun run dev
# Visit http://localhost:3000
bun run dev # http://localhost:3000
```
### Project Structure
- `source/` - Edit these! Single source of truth for all content
- `dist/` - Generated provider-specific files (committed for users)
- `api/` - Vercel Functions for production (serverless)
- `public/` - Website (HTML, CSS modules, vanilla JS)
- `server/` - Bun server for local development
- `scripts/` - Build system that transforms source → dist
- `source/` - Single source of truth for all content
- `dist/` - Generated provider-specific files
- `public/` - Website
- `scripts/` - Build system
### Deployment
See [DEVELOP.md](DEVELOP.md) for contributor guidelines.
The site runs on [Vercel](https://vercel.com) with [Bun runtime](https://vercel.com/docs/functions/runtimes/bun).
## Provider Comparison
**Architecture:**
- **Local dev**: Monolithic Bun server (`server/index.js`) with native routing
- **Production**: Individual Vercel Functions (`api/` directory) for serverless deployment
- **Shared logic**: Both environments import from `server/lib/api-handlers.js` (zero duplication)
Push to main and Vercel auto-deploys:
```bash
# Build generates dist/ files and ZIPs
bun run build
# For local testing
bun run dev # Uses server/index.js
```
See [DEVELOP.md](DEVELOP.md) for detailed contributor guidelines.
## Contributing
Want to add more design skills or commands? See [DEVELOP.md](DEVELOP.md) for contributor guidelines.
This is an open-source project hosted on [GitHub](https://github.com/pbakaus/vibe-design-plugins).
| Feature | Cursor | Claude Code | Gemini CLI | Codex CLI |
|---------|--------|-------------|------------|-----------|
| Command Args | No | Yes | Yes | Yes |
| Frontmatter | No | Yes | Yes (TOML) | Yes |
| Modular Skills | No | No | Yes | Yes |
## License
See LICENSE file.
---
Created by [Paul Bakaus](https://www.paulbakaus.com)