devtronic 1.2.2 → 1.2.4

package/templates/addons/design-best-practices/skills/design-init/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: design-init
+description: One-time project design context setup — gathers visual direction, constraints, and writes Design Context to CLAUDE.md
+user-invokable: true
+---
+
+# Design Init
+
+Establish the design context for this project through a structured interview. Writes a **Design Context** section to CLAUDE.md so all future design work is grounded in project-specific decisions.
+
+## When to Use
+
+- First time working on frontend/UI for a project
+- After a major design direction change
+- When onboarding a new AI agent to an existing design system
+
+**Run once per project.** The output persists in CLAUDE.md.
+
+---
+
+## Process
+
+### 1. Codebase Scan
+
+Before asking questions, scan the project for existing design signals:
+
+- **CSS/Tailwind config** — existing color tokens, spacing scale, font stacks
+- **Component library** — shadcn/ui, Radix, MUI, custom components
+- **Design tokens** — CSS custom properties, Tailwind theme, Sass variables
+- **Existing patterns** — card styles, button variants, layout grids
+
+### 2. Context Interview
+
+Ask the user about:
+
+**Visual Direction**
+- What is the product? Who are the users?
+- What mood should the design convey? (e.g., professional, playful, minimal, editorial)
+- Any reference sites or design systems to draw from?
+
+**Constraints**
+- Existing design system or brand guidelines?
+- Accessibility requirements (WCAG AA, AAA)?
+- Device targets (mobile-first, desktop-first, responsive)?
+- Internationalization needs (RTL, long text, CJK)?
+
+**Typography**
+- Preferred font families (or "use system fonts")?
+- Type scale approach (modular, custom, Tailwind defaults)?
+
+**Color**
+- Brand colors (hex values)?
+- Light mode, dark mode, or both?
+- Color palette strategy (neutral-first, vibrant, muted)?
+
+### 3. Write Design Context
+
+Append a `## Design Context` section to CLAUDE.md:
+
+```markdown
+## Design Context
+
+### Visual Direction
+[mood, references, personality]
+
+### Typography
+- Display: [font], [weights]
+- Body: [font], [weights]
+- Scale: [approach]
+
+### Color Palette
+- Background: [hex]
+- Surface: [hex]
+- Text primary: [hex]
+- Text secondary: [hex]
+- Accent: [hex]
+- Error/Warning/Success: [hex values]
+
+### Spacing
+- Base unit: [4px/8px]
+- Scale: [values]
+
+### Constraints
+- Accessibility: [level]
+- Responsive: [approach]
+- i18n: [requirements]
+```
+
+---
+
+## Tips
+
+- If the user says "just use defaults", write sensible defaults with system fonts, 4px grid, neutral palette
+- Reference the project's existing tokens/config rather than inventing new ones
+- Keep the output concise — this is a reference, not a design spec

package/templates/addons/design-best-practices/skills/design-refine/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: design-refine
+description: Directional design refinement — push the design bolder, quieter, more minimal, or more delightful
+user-invokable: true
+args:
+  - name: direction
+    description: "Refinement direction: bolder, quieter, minimal, delightful"
+    required: true
+---
+
+# Design Refine
+
+Apply a directional design transformation to existing UI. Each direction has a distinct set of moves that shift the design's personality without breaking functionality.
+
+## Usage
+
+```
+/design-refine --direction bolder
+/design-refine --direction quieter
+/design-refine --direction minimal
+/design-refine --direction delightful
+```
+
+---
+
+## Mandatory Pre-Check
+
+Before refining:
+1. Read the Design Context from CLAUDE.md
+2. Identify the target files/components
+3. Run a quick design-review to understand current state
+4. Confirm direction with the user if ambiguous
+
+---
+
+## Directions
+
+### Bolder
+
+Push the design toward more visual impact and confidence.
+
+**Moves:**
+- Increase type scale contrast (larger headlines, smaller labels)
+- Strengthen the accent color or introduce a second accent
+- Add asymmetric layout elements — break the grid intentionally
+- Increase whitespace around hero elements
+- Use heavier font weights for display text
+- Add a single dramatic visual moment (oversized number, full-bleed image, bold divider)
+
+**Anti-patterns to avoid:**
+- Don't make everything bold — select 1-2 elements to amplify
+- Don't add gradients/shadows for "boldness" — use scale and weight
+- Don't sacrifice readability for impact
+
+### Quieter
+
+Pull the design toward restraint, sophistication, and calm.
+
+**Moves:**
+- Reduce color saturation across the palette
+- Increase whitespace between sections
+- Soften type hierarchy — less extreme size jumps
+- Use lighter font weights for headings
+- Remove decorative elements that don't serve function
+- Mute borders and dividers (lighter colors, thinner strokes)
+
+**Anti-patterns to avoid:**
+- Don't make text too light to read — quiet ≠ invisible
+- Don't flatten all hierarchy — some contrast is still needed
+- Don't remove interactive affordances
+
+### Minimal
+
+Strip the design to its essential elements.
+
+**Moves:**
+- Remove cards/containers — let content sit on the surface
+- Reduce to 2-3 colors maximum (background, text, one accent)
+- Use a single font family with weight/size for hierarchy
+- Replace icons with text labels where possible
+- Remove borders — use spacing to define groups
+- Eliminate decorative elements entirely
+
+**Anti-patterns to avoid:**
+- Don't remove navigation or wayfinding cues
+- Don't make the UI ambiguous — clarity over minimalism
+- Don't sacrifice accessibility for aesthetics
+
+### Delightful
+
+Add warmth, personality, and small moments of joy.
+
+**Moves:**
+- Add subtle micro-interactions (button press, toggle switch, state transitions)
+- Use a warmer color temperature in neutrals
+- Add personality to empty states (friendly copy, simple illustration)
+- Introduce slight border-radius variety (not everything the same)
+- Add a subtle texture or pattern to one surface
+- Use playful but readable microcopy
+
+**Anti-patterns to avoid:**
+- Don't add animation to everything — pick 2-3 moments
+- Don't use clip-art style illustrations — keep quality high
+- Don't sacrifice performance for delight (heavy animations)
+- Don't make the UI feel childish when the product is serious
+
+---
+
+## Process
+
+1. **Confirm direction** with the user
+2. **Identify 3-5 specific moves** from the direction's list that apply to this UI
+3. **Apply changes** incrementally — one move at a time
+4. **Review after each move** — does it push the right direction without breaking anything?
+5. **Summarize** what was changed and why
+
+---
+
+## Tips
+
+- Refinement is about shifting a slider, not flipping a switch
+- Each direction should be noticeable but not jarring
+- The best refinement feels like the design "was always supposed to be this way"
+- Combine directions carefully: bolder + minimal can work; bolder + delightful often clashes

package/templates/addons/design-best-practices/skills/design-review/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: design-review
+description: Design critique with AI slop detection — visual hierarchy, information architecture, emotional resonance, actionable report
+user-invokable: true
+---
+
+# Design Review
+
+Perform a structured design critique on the current UI. Produces an actionable report covering visual quality, hierarchy, accessibility, and AI slop detection.
+
+## When to Use
+
+- After implementing a new page or component
+- Before shipping UI changes
+- When UI "feels off" but you can't pinpoint why
+- Periodic design quality audits
+
+---
+
+## Process
+
+### 1. Gather Context
+
+- Read the Design Context from CLAUDE.md (if exists)
+- Identify the files/components under review
+- Understand the purpose of the UI being reviewed
+
+### 2. AI Slop Test
+
+Check for common AI-generated design anti-patterns:
+
+| Signal | What to Look For |
+|--------|-----------------|
+| Generic gradients | Blue/purple gradients with no design rationale |
+| Border-radius abuse | Everything is a pill or has identical rounding |
+| Shadow soup | Drop shadows on every element |
+| Meaningless animation | Hover scales/glows on non-interactive elements |
+| Placeholder copy | "Welcome to our platform", "Lorem ipsum" in production |
+| Color overload | Rainbow dashboards, competing accents |
+| Flat hierarchy | Everything has equal visual weight |
+| Card-itis | Every piece of information boxed in a card |
+
+**Severity**: Flag each as `slop` (definite AI pattern) or `risk` (borderline).
+
+### 3. Visual Hierarchy Audit
+
+- Is there a clear focal point on each view?
+- Does the type hierarchy communicate importance? (H1 > H2 > body > caption)
+- Is whitespace used intentionally to group and separate?
+- Are interactive elements visually distinct from static content?
+
+### 4. Information Architecture
+
+- Is the content structure logical?
+- Can users find what they need without thinking?
+- Are labels clear and consistent?
+- Do empty states guide users toward action?
+
+### 5. Emotional Resonance
+
+- Does the design match the intended mood/brand?
+- Is there a human touch (warmth, personality)?
+- Would a real user trust this interface?
+
+### 6. Accessibility Quick Check
+
+- Color contrast ratios (4.5:1 body text, 3:1 large text)
+- Focus indicators visible?
+- Touch targets adequate (44x44px minimum)?
+- Screen reader landmarks present?
+
+---
+
+## Output Format
+
+```markdown
+## Design Review: [Component/Page Name]
+
+### AI Slop Score: [0-10] (0 = no slop, 10 = fully generic)
+
+**Flagged patterns:**
+- [pattern]: [severity] — [specific location and fix]
+
+### Visual Hierarchy: [Strong / Adequate / Weak]
+- [finding 1]
+- [finding 2]
+
+### Information Architecture: [Clear / Adequate / Confused]
+- [finding 1]
+
+### Accessibility: [Pass / Needs Work / Fail]
+- [finding 1]
+
+### Recommended Actions (priority order)
+1. [Most impactful fix]
+2. [Second fix]
+3. [Third fix]
+```
+
+---
+
+## Tips
+
+- Be specific: "The card shadow is too heavy at `shadow-lg`" not "shadows need work"
+- Suggest concrete CSS/Tailwind changes
+- Reference the Design Context for project-specific standards
+- Praise what works — don't just list problems

package/templates/addons/design-best-practices/skills/design-system/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: design-system
+description: Design system extraction and normalization — find patterns or apply consistent tokens across the codebase
+user-invokable: true
+args:
+  - name: mode
+    description: "Mode: extract (find patterns and tokens) or normalize (apply system consistently)"
+    required: true
+---
+
+# Design System
+
+Two modes for working with design tokens and patterns:
+
+- **Extract** — Scan the codebase, find recurring values, propose a token system
+- **Normalize** — Apply an existing token system consistently across all files
+
+## Usage
+
+```
+/design-system --mode extract
+/design-system --mode normalize
+```
+
+---
+
+## Extract Mode
+
+Scan the codebase for design patterns and propose a unified token system.
+
+### Process
+
+1. **Scan for values**
+   - Colors: hex, rgb, hsl, oklch values in CSS/Tailwind/JS
+   - Typography: font sizes, weights, line heights, font families
+   - Spacing: margin, padding, gap values
+   - Borders: radius values, border widths, colors
+   - Shadows: box-shadow definitions
+   - Breakpoints: media query values
+
+2. **Cluster similar values**
+   - Group colors within ΔE < 3 (perceptually identical)
+   - Group spacing within 2px tolerance
+   - Identify size scale patterns (linear, modular)
+
+3. **Propose token system**
+
+   ```
+   ## Extracted Design Tokens
+
+   ### Colors (N unique → M tokens)
+   --color-bg: #fafafa (used 23 times as #fafafa, #f9f9f9, #fafbfc)
+   --color-text: #1a1a1a (used 18 times as #1a1a1a, #171717, #1c1c1c)
+   ...
+
+   ### Typography (N declarations → M scale steps)
+   --text-xs: 12px (used 8 times)
+   --text-sm: 14px (used 15 times)
+   ...
+
+   ### Spacing (N values → M tokens)
+   --space-1: 4px
+   --space-2: 8px
+   ...
+   ```
+
+4. **Flag inconsistencies**
+   - Near-duplicate colors that should be unified
+   - Off-grid spacing values
+   - Typography values that don't fit a scale
+   - Hardcoded values that should reference tokens
+
+### Output
+
+A report with:
+- Proposed token definitions (CSS custom properties or Tailwind config)
+- Migration checklist: which files need which replacements
+- Inconsistency count and severity
+
+---
+
+## Normalize Mode
+
+Apply an existing design system (from Design Context, Tailwind config, or CSS custom properties) consistently across the codebase.
+
+### Process
+
+1. **Load the canonical token system**
+   - Read Design Context from CLAUDE.md
+   - Read Tailwind config (`tailwind.config.*`)
+   - Read CSS custom properties (`:root` declarations)
+
+2. **Scan for deviations**
+   - Find hardcoded values that should use tokens
+   - Find near-matches (e.g., `#333` when `--text-primary` is `#2d2d2d`)
+   - Find inconsistent patterns (some buttons use tokens, others don't)
+
+3. **Apply corrections**
+   - Replace hardcoded values with token references
+   - Unify near-duplicate values to the canonical token
+   - Update component styles to use the design system
+
+4. **Generate migration report**
+
+   ```
+   ## Normalization Report
+
+   ### Files Modified: N
+   ### Replacements: M
+
+   | File | Change | Before → After |
+   |------|--------|---------------|
+   | Button.tsx | color | #333 → var(--text-primary) |
+   | Card.tsx | spacing | 18px → var(--space-5) |
+   ```
+
+---
+
+## Tips
+
+- Run extract before normalize on projects without a formal design system
+- Extract can reveal design debt — use it for audits
+- Normalize is non-destructive: review the migration report before applying
+- For Tailwind projects, prefer theme config tokens over CSS custom properties
+- Consider running design-review after normalize to verify visual consistency