this repo has no description
shorten skills, add install instructions and adjust AGENTS.md
+1201
-5904
+13
-2
AGENTS.md
+13
-2
AGENTS.md
···
1
-
<!-- base -->
1
+
<!-- BASE START -->
2
2
## Interaction Guidelines
3
3
4
4
Direct, succinct, and objective. Favor headings over lists; use nested lists only for specific details.
···
33
33
- **Dual Getter-Setter Functions**: Use overloaded functions for state: `fn()` to get, `fn(val)` to set.
34
34
- **Interface Quality**: Prioritize high-fidelity UI/UX and seamless DX.
35
35
36
+
### Error Handling
37
+
- **Graceful Degradation**: Ensure system continues to operate in reduced capacity when errors occur.
38
+
- **Informative Feedback**: Provide clear, actionable error messages to users and developers.
39
+
- **Robust Logging**: Implement comprehensive logging for debugging and monitoring.
40
+
36
41
### Performance and Scale
37
42
38
43
- **Efficiency**: Favor built-in language features and efficient algorithms.
39
44
- **Consistency**: Maintain unified style for predictability.
45
+
46
+
### Safety
47
+
- Do not run the dev server or compile/build, assume the user is already doing that.
48
+
- Do not perform any irreversible actions without explicit user confirmation.
49
+
- Do not commit and push unless told to. When told to, separate large commits into logical chunks with clear messages.
50
+
- Before finishing a task, run the check commands to lint, type check and format.
40
51
<!-- end base -->
41
52
42
53
<!-- caveman mode -->
43
54
Respond terse like smart caveman. All technical substance stay. Only fluff die.
44
55
45
56
Rules:
46
-
- Drop: articles (a/an/the), filler (just/really/basically), pleasantries, hedging
57
+
- Drop: articles (//), filler (//), pleasantries, hedging
47
58
- Fragments OK. Short synonyms. Technical terms exact. Code unchanged.
48
59
- Pattern: [thing] [action] [reason]. [next step].
49
60
- Not: "Sure! I'd be happy to help you with that."
+24
-8
README.md
+24
-8
README.md
···
2
2
3
3
A curated collection of agent skills for design, frontend work, and cave tooling.
4
4
5
+
## Install
6
+
7
+
<details>
8
+
<summary>Bun</summary>
9
+
```bash
10
+
bunx --bun skills add davidbasilefilho/skills
11
+
```
12
+
</details>
13
+
<details>
14
+
<summary>npm</summary>
15
+
```bash
16
+
npx -y skills add davidbasilefilho/skills
17
+
```
18
+
</details>
19
+
20
+
5
21
## What is in this repo
6
22
7
-
Each directory under `skills/` contains a standalone skill definition. Skills are designed to help agents perform focused tasks such as improving layout, tightening copy, adding motion, auditing interfaces, or coordinating cave workflows.
23
+
Each directory under `skills/` contains standalone skill definition. Skills are designed to help agents perform focused tasks such as improving layout, tightening copy, adding motion, auditing interfaces, or coordinating cave workflows.
8
24
9
25
## Included skills
10
26
···
13
29
- `arrange` - Improve layout, spacing, and visual rhythm
14
30
- `audit` - Run technical quality checks across accessibility and performance
15
31
- `bolder` - Make safe designs more visually assertive
16
-
- `cavecrew` - Coordinate a crew-oriented workflow for cave tools
17
-
- `caveman` - Main entry point for the caveman toolset
32
+
- `cavecrew` - Coordinate crew-oriented workflow for cave tools
33
+
- `caveman` - Main entry point for caveman toolset
18
34
- `caveman-commit` - Create commits with caveman workflows
19
35
- `caveman-compress` - Compress work and context for cave tools
20
-
- `caveman-help` - Show help for the caveman toolset
36
+
- `caveman-help` - Show help for caveman toolset
21
37
- `caveman-review` - Review work with caveman workflows
22
38
- `caveman-stats` - Report caveman usage and stats
23
39
- `clarify` - Improve UX copy, labels, and instructions
24
40
- `colorize` - Add strategic color and visual warmth
25
41
- `compress` - Reduce output and context for cave workflows
26
-
- `critique` - Review a design from a UX perspective
42
+
- `critique` - Review design from UX perspective
27
43
- `delight` - Add moments of joy and personality
28
44
- `distill` - Simplify designs by removing unnecessary complexity
29
45
- `extract` - Consolidate reusable components and design tokens
···
37
53
- `overdrive` - Push designs further when they need stronger impact
38
54
- `polish` - Refine interfaces with finishing touches
39
55
- `quieter` - Reduce noise and visual clutter
40
-
- `teach-impeccable` - Establish the design context required by frontend skills
56
+
- `teach-impeccable` - Establish design context required by frontend skills
41
57
- `typeset` - Improve typography and text presentation
42
58
- `ulw` - Create ultra-lightweight experiences
43
59
44
60
## Usage
45
61
46
-
How a skill is invoked depends on the agent harness or editor integration you are using. In general, select the relevant skill for the task and load its `SKILL.md` instructions before working.
62
+
How skill is invoked depends on agent harness or editor integration you are using. In general, select relevant skill for task and load its `SKILL.md` instructions before working.
47
63
48
64
## Repository structure
49
65
···
55
71
56
72
## Contributing
57
73
58
-
- Keep each skill focused on a single job
74
+
- Keep each skill focused on single job
59
75
- Prefer clear, direct instructions over duplicated guidance
60
76
- Update this README when adding or renaming skills
61
77
-35
plan.md
-35
plan.md
···
1
-
# Implementation Plan
2
-
3
-
## Goal
4
-
Apply the compress skill to every eligible text file under `./skills`, excluding `ulw`, `shadcn`, `cave*`, and `compress`.
5
-
6
-
## Tasks
7
-
1. **Define the target file set**: Enumerate all text files under `./skills` and filter out excluded skill trees.
8
-
- File: `./skills/**`
9
-
- Changes: Treat eligible files as markdown and other text files such as `SKILL.md`, `README.md`, `WARP.md`, `cli.md`, `customization.md`, `mcp.md`, and `rules/*.md`, while excluding anything under `./skills/ulw/`, `./skills/shadcn/`, `./skills/cave*/`, and `./skills/compress/`.
10
-
- Acceptance: A final file list exists before any edits, and it contains no excluded paths.
11
-
12
-
2. **Run compression on eligible files only**: Invoke the compress skill once per target file, preserving code blocks, backticks, URLs, and technical terms.
13
-
- File: each file in the target set
14
-
- Changes: Overwrite each file with its caveman-compressed version and create `.original.md` backups as the skill requires.
15
-
- Acceptance: Every eligible file is processed successfully, and no excluded file is modified.
16
-
17
-
3. **Verify results and exclusions**: Check that backups were created and that excluded directories remained unchanged.
18
-
- File: processed targets plus exclusion paths
19
-
- Changes: Compare a sample or full diff of compressed files, confirm `.original.md` backups exist for edited files, and confirm excluded paths have no diffs.
20
-
- Acceptance: Modified files show compressed prose, backups are present, and excluded trees are untouched.
21
-
22
-
## Files to Modify
23
-
- `./skills/**` - eligible text files only, excluding `ulw`, `shadcn`, `cave*`, and `compress` trees.
24
-
25
-
## New Files
26
-
- `./skills/**/*.original.md` - human-readable backups created by the compress workflow.
27
-
28
-
## Dependencies
29
-
- Task 1 must complete before Task 2.
30
-
- Task 2 must complete before Task 3.
31
-
32
-
## Risks
33
-
- The exclusion rule `cave*` is broad and may exclude both `cavecrew` and `caveman*` trees, so the exact match scope should be confirmed before execution.
34
-
- Mixed-content markdown files may contain code blocks that must remain verbatim.
35
-
- If any non-markdown text files exist under `./skills`, they need manual review to confirm they are safe to compress.
+4
-4
skills/adapt/SKILL.md
+4
-4
skills/adapt/SKILL.md
···
1
1
---
2
2
name: adapt
3
-
description: "Adapt designs to work across different screen sizes, devices, contexts, or platforms. Implements breakpoints, fluid layouts, and touch targets. Use when the user mentions responsive design, mobile layouts, breakpoints, viewport adaptation, or cross-device compatibility."
3
+
description: "Adapt designs to work across different screen sizes, devices, contexts, or platforms. Implements breakpoints, fluid layouts, and touch targets. Use when user mentions responsive design, mobile layouts, breakpoints, viewport adaptation, or cross-device compatibility."
4
4
argument-hint: "[target] [context (mobile, tablet, print...)]"
5
5
user-invocable: true
6
6
---
···
9
9
10
10
## MANDATORY PREPARATION
11
11
12
-
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. gather: target platforms or devices and usage contexts.
12
+
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and Context Gathering Protocol. Follow protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. gather: target platforms or devices and usage contexts.
13
13
14
14
---
15
15
···
35
35
- What will not work? (Hover states on touch, tiny touch targets)
36
36
- What is inappropriate? (Desktop patterns on mobile, mobile patterns on desktop)
37
37
38
-
**CRITICAL**: Adaptation is not scaling. It is rethinking the experience for the new context.
38
+
**CRITICAL**: Adaptation is not scaling. it's rethinking experience for new context.
39
39
40
40
## Plan Adaptation Strategy
41
41
···
195
195
- **Edge cases**: Very small screens (320px), very large screens (4K)
196
196
- **Slow connections**: Test on throttled network
197
197
198
-
Remember: You are a cross-platform design expert. Make experiences that feel native to each context while maintaining brand and functionality consistency. Adapt intentionally, test thoroughly.
198
+
Remember: You are cross-platform design expert. Make experiences that feel native to each context while maintaining brand and functionality consistency. Adapt intentionally, test thoroughly.
-198
skills/adapt/SKILL.md.original.md
-198
skills/adapt/SKILL.md.original.md
···
1
-
---
2
-
name: adapt
3
-
description: "Adapt designs to work across different screen sizes, devices, contexts, or platforms. Implements breakpoints, fluid layouts, and touch targets. Use when the user mentions responsive design, mobile layouts, breakpoints, viewport adaptation, or cross-device compatibility."
4
-
argument-hint: "[target] [context (mobile, tablet, print...)]"
5
-
user-invocable: true
6
-
---
7
-
8
-
Adapt existing designs to work effectively across different contexts: different screen sizes, devices, platforms, or use cases.
9
-
10
-
## MANDATORY PREPARATION
11
-
12
-
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. Additionally gather: target platforms or devices and usage contexts.
13
-
14
-
---
15
-
16
-
## Assess Adaptation Challenge
17
-
18
-
Understand what needs adaptation and why.
19
-
20
-
### 1. Identify the source context
21
-
- What was it designed for originally? (Desktop web? Mobile app?)
22
-
- What assumptions were made? (Large screen? Mouse input? Fast connection?)
23
-
- What works well in current context?
24
-
25
-
### 2. Understand target context
26
-
- **Device**: Mobile, tablet, desktop, TV, watch, print?
27
-
- **Input method**: Touch, mouse, keyboard, voice, gamepad?
28
-
- **Screen constraints**: Size, resolution, orientation?
29
-
- **Connection**: Fast wifi, slow 3G, offline?
30
-
- **Usage context**: On-the-go vs desk, quick glance vs focused reading?
31
-
- **User expectations**: What do users expect on this platform?
32
-
33
-
### 3. Identify adaptation challenges
34
-
- What will not fit? (Content, navigation, features)
35
-
- What will not work? (Hover states on touch, tiny touch targets)
36
-
- What is inappropriate? (Desktop patterns on mobile, mobile patterns on desktop)
37
-
38
-
**CRITICAL**: Adaptation is not just scaling. It is rethinking the experience for the new context.
39
-
40
-
## Plan Adaptation Strategy
41
-
42
-
Create context-appropriate strategy.
43
-
44
-
### Mobile Adaptation (Desktop to Mobile)
45
-
46
-
**Layout Strategy**:
47
-
- Single column instead of multi-column
48
-
- Vertical stacking instead of side-by-side
49
-
- Full-width components instead of fixed widths
50
-
- Bottom navigation instead of top or side navigation
51
-
52
-
**Interaction Strategy**:
53
-
- Touch targets 44x44px minimum (not hover-dependent)
54
-
- Swipe gestures where appropriate (lists, carousels)
55
-
- Bottom sheets instead of dropdowns
56
-
- Thumbs-first design (controls within thumb reach)
57
-
- Larger tap areas with more spacing
58
-
59
-
**Content Strategy**:
60
-
- Progressive disclosure (do not show everything at once)
61
-
- Prioritize primary content (secondary content in tabs or accordions)
62
-
- Shorter text (more concise)
63
-
- Larger text (16px minimum)
64
-
65
-
**Navigation Strategy**:
66
-
- Hamburger menu or bottom navigation
67
-
- Reduce navigation complexity
68
-
- Sticky headers for context
69
-
- Back button in navigation flow
70
-
71
-
### Tablet Adaptation (Hybrid Approach)
72
-
73
-
**Layout Strategy**:
74
-
- Two-column layouts (not single or three-column)
75
-
- Side panels for secondary content
76
-
- Master-detail views (list plus detail)
77
-
- Adaptive based on orientation (portrait vs landscape)
78
-
79
-
**Interaction Strategy**:
80
-
- Support both touch and pointer
81
-
- Touch targets 44x44px but allow denser layouts than phone
82
-
- Side navigation drawers
83
-
- Multi-column forms where appropriate
84
-
85
-
### Desktop Adaptation (Mobile to Desktop)
86
-
87
-
**Layout Strategy**:
88
-
- Multi-column layouts (use horizontal space)
89
-
- Side navigation always visible
90
-
- Multiple information panels simultaneously
91
-
- Fixed widths with max-width constraints (do not stretch to 4K)
92
-
93
-
**Interaction Strategy**:
94
-
- Hover states for additional information
95
-
- Keyboard shortcuts
96
-
- Right-click context menus
97
-
- Drag and drop where helpful
98
-
- Multi-select with Shift or Cmd
99
-
100
-
**Content Strategy**:
101
-
- Show more information upfront (less progressive disclosure)
102
-
- Data tables with many columns
103
-
- Richer visualizations
104
-
- More detailed descriptions
105
-
106
-
### Print Adaptation (Screen to Print)
107
-
108
-
**Layout Strategy**:
109
-
- Page breaks at logical points
110
-
- Remove navigation, footer, interactive elements
111
-
- Black and white (or limited color)
112
-
- Proper margins for binding
113
-
114
-
**Content Strategy**:
115
-
- Expand shortened content (show full URLs, hidden sections)
116
-
- Add page numbers, headers, footers
117
-
- Include metadata (print date, page title)
118
-
- Convert charts to print-friendly versions
119
-
120
-
### Email Adaptation (Web to Email)
121
-
122
-
**Layout Strategy**:
123
-
- Narrow width (600px max)
124
-
- Single column only
125
-
- Inline CSS (no external stylesheets)
126
-
- Table-based layouts (for email client compatibility)
127
-
128
-
**Interaction Strategy**:
129
-
- Large, obvious CTAs (buttons not text links)
130
-
- No hover states (not reliable)
131
-
- Deep links to web app for complex interactions
132
-
133
-
## Implement Adaptations
134
-
135
-
Apply changes systematically.
136
-
137
-
### Responsive Breakpoints
138
-
139
-
Choose appropriate breakpoints:
140
-
- Mobile: 320px-767px
141
-
- Tablet: 768px-1023px
142
-
- Desktop: 1024px+
143
-
- Or content-driven breakpoints (where design breaks)
144
-
145
-
### Layout Adaptation Techniques
146
-
147
-
- **CSS Grid or Flexbox**: Reflow layouts automatically
148
-
- **Container Queries**: Adapt based on container, not viewport
149
-
- **clamp()**: Fluid sizing between min and max
150
-
- **Media queries**: Different styles for different contexts
151
-
- **Display properties**: Show or hide elements per context
152
-
153
-
### Touch Adaptation
154
-
155
-
- Increase touch target sizes (44x44px minimum)
156
-
- Add more spacing between interactive elements
157
-
- Remove hover-dependent interactions
158
-
- Add touch feedback (ripples, highlights)
159
-
- Consider thumb zones (easier to reach bottom than top)
160
-
161
-
### Content Adaptation
162
-
163
-
- Use display: none sparingly (still downloads)
164
-
- Progressive enhancement (core content first, enhancements on larger screens)
165
-
- Lazy loading for off-screen content
166
-
- Responsive images (srcset, picture element)
167
-
168
-
### Navigation Adaptation
169
-
170
-
- Transform complex nav to hamburger or drawer on mobile
171
-
- Bottom nav bar for mobile apps
172
-
- Persistent side navigation on desktop
173
-
- Breadcrumbs on smaller screens for context
174
-
175
-
**IMPORTANT**: Test on real devices, not just browser DevTools. Device emulation is helpful but not perfect.
176
-
177
-
**NEVER**:
178
-
- Hide core functionality on mobile (if it matters, make it work)
179
-
- Assume desktop equals powerful device (consider accessibility, older machines)
180
-
- Use different information architecture across contexts (confusing)
181
-
- Break user expectations for platform (mobile users expect mobile patterns)
182
-
- Forget landscape orientation on mobile or tablet
183
-
- Use generic breakpoints blindly (use content-driven breakpoints)
184
-
- Ignore touch on desktop (many desktop devices have touch)
185
-
186
-
## Verify Adaptations
187
-
188
-
Test thoroughly across contexts.
189
-
190
-
- **Real devices**: Test on actual phones, tablets, desktops
191
-
- **Different orientations**: Portrait and landscape
192
-
- **Different browsers**: Safari, Chrome, Firefox, Edge
193
-
- **Different OS**: iOS, Android, Windows, macOS
194
-
- **Different input methods**: Touch, mouse, keyboard
195
-
- **Edge cases**: Very small screens (320px), very large screens (4K)
196
-
- **Slow connections**: Test on throttled network
197
-
198
-
Remember: You are a cross-platform design expert. Make experiences that feel native to each context while maintaining brand and functionality consistency. Adapt intentionally, test thoroughly.
+6
-6
skills/animate/SKILL.md
+6
-6
skills/animate/SKILL.md
···
1
1
---
2
2
name: animate
3
-
description: "Review a feature and enhance it with purposeful animations, micro-interactions, and motion effects that improve usability and delight. Use when the user mentions adding animation, transitions, micro-interactions, motion design, hover effects, or making the UI feel more alive."
3
+
description: "Review feature and enhance it with purposeful animations, micro-interactions, and motion effects that improve usability and delight. Use when user mentions adding animation, transitions, micro-interactions, motion design, hover effects, or making UI feel more alive."
4
4
argument-hint: "[target]"
5
5
user-invocable: true
6
6
---
7
7
8
-
Analyze a feature and strategically add animations and micro-interactions that enhance understanding, provide feedback, and create delight.
8
+
Analyze feature and strategically add animations and micro-interactions that enhance understanding, provide feedback, and create delight.
9
9
10
10
## MANDATORY PREPARATION
11
11
12
-
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. gather: performance constraints.
12
+
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and Context Gathering Protocol. Follow protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. gather: performance constraints.
13
13
14
14
---
15
15
16
16
## Assess Animation Opportunities
17
17
18
-
Analyze where motion would improve the experience.
18
+
Analyze where motion would improve experience.
19
19
20
20
### 1. Identify static areas
21
21
- **Missing feedback**: Actions without visual acknowledgment (button clicks, form submission, etc.)
···
30
30
- Who is audience? (Motion-sensitive users? Power users who want speed?)
31
31
- What matters most? (One hero animation vs many micro-interactions?)
32
32
33
-
If any of these are unclear from the codebase, {{ask_instruction}}
33
+
If any of these are unclear from codebase, {{ask_instruction}}
34
34
35
35
**CRITICAL**: Respect prefers-reduced-motion. Always provide non-animated alternatives for users who need them.
36
36
37
37
## Plan Animation Strategy
38
38
39
-
Create a purposeful animation plan.
39
+
Create purposeful animation plan.
40
40
41
41
- **Hero moment**: What is ONE signature animation? (Page load? Hero section? Key interaction?)
42
42
- **Feedback layer**: Which interactions need acknowledgment?
-174
skills/animate/SKILL.md.original.md
-174
skills/animate/SKILL.md.original.md
···
1
-
---
2
-
name: animate
3
-
description: "Review a feature and enhance it with purposeful animations, micro-interactions, and motion effects that improve usability and delight. Use when the user mentions adding animation, transitions, micro-interactions, motion design, hover effects, or making the UI feel more alive."
4
-
argument-hint: "[target]"
5
-
user-invocable: true
6
-
---
7
-
8
-
Analyze a feature and strategically add animations and micro-interactions that enhance understanding, provide feedback, and create delight.
9
-
10
-
## MANDATORY PREPARATION
11
-
12
-
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. Additionally gather: performance constraints.
13
-
14
-
---
15
-
16
-
## Assess Animation Opportunities
17
-
18
-
Analyze where motion would improve the experience.
19
-
20
-
### 1. Identify static areas
21
-
- **Missing feedback**: Actions without visual acknowledgment (button clicks, form submission, etc.)
22
-
- **Jarring transitions**: Instant state changes that feel abrupt (show or hide, page loads, route changes)
23
-
- **Unclear relationships**: Spatial or hierarchical relationships that are not obvious
24
-
- **Lack of delight**: Functional but joyless interactions
25
-
- **Missed guidance**: Opportunities to direct attention or explain behavior
26
-
27
-
### 2. Understand the context
28
-
- What is the personality? (Playful vs serious, energetic vs calm)
29
-
- What is the performance budget? (Mobile-first? Complex page?)
30
-
- Who is the audience? (Motion-sensitive users? Power users who want speed?)
31
-
- What matters most? (One hero animation vs many micro-interactions?)
32
-
33
-
If any of these are unclear from the codebase, {{ask_instruction}}
34
-
35
-
**CRITICAL**: Respect prefers-reduced-motion. Always provide non-animated alternatives for users who need them.
36
-
37
-
## Plan Animation Strategy
38
-
39
-
Create a purposeful animation plan.
40
-
41
-
- **Hero moment**: What is the ONE signature animation? (Page load? Hero section? Key interaction?)
42
-
- **Feedback layer**: Which interactions need acknowledgment?
43
-
- **Transition layer**: Which state changes need smoothing?
44
-
- **Delight layer**: Where can we surprise and delight?
45
-
46
-
**IMPORTANT**: One well-orchestrated experience beats scattered animations everywhere. Focus on high-impact moments.
47
-
48
-
## Implement Animations
49
-
50
-
Add motion systematically across these categories.
51
-
52
-
### Entrance Animations
53
-
- **Page load choreography**: Stagger element reveals (100-150ms delays), fade and slide combinations
54
-
- **Hero section**: Dramatic entrance for primary content (scale, parallax, or creative effects)
55
-
- **Content reveals**: Scroll-triggered animations using intersection observer
56
-
- **Modal or drawer entry**: Smooth slide and fade, backdrop fade, focus management
57
-
58
-
### Micro-interactions
59
-
- **Button feedback**:
60
-
- Hover: Subtle scale (1.02-1.05), color shift, shadow increase
61
-
- Click: Quick scale down then up (0.95 to 1), ripple effect
62
-
- Loading: Spinner or pulse state
63
-
- **Form interactions**:
64
-
- Input focus: Border color transition, slight scale or glow
65
-
- Validation: Shake on error, check mark on success, smooth color transitions
66
-
- **Toggle switches**: Smooth slide and color transition (200-300ms)
67
-
- **Checkboxes or radio**: Check mark animation, ripple effect
68
-
- **Like or favorite**: Scale and rotation, particle effects, color transition
69
-
70
-
### State Transitions
71
-
- **Show or hide**: Fade and slide (not instant), appropriate timing (200-300ms)
72
-
- **Expand or collapse**: Height transition with overflow handling, icon rotation
73
-
- **Loading states**: Skeleton screen fades, spinner animations, progress bars
74
-
- **Success or error**: Color transitions, icon animations, gentle scale pulse
75
-
- **Enable or disable**: Opacity transitions, cursor changes
76
-
77
-
### Navigation and Flow
78
-
- **Page transitions**: Crossfade between routes, shared element transitions
79
-
- **Tab switching**: Slide indicator, content fade or slide
80
-
- **Carousel or slider**: Smooth transforms, snap points, momentum
81
-
- **Scroll effects**: Parallax layers, sticky headers with state changes, scroll progress indicators
82
-
83
-
### Feedback and Guidance
84
-
- **Hover hints**: Tooltip fade-ins, cursor changes, element highlights
85
-
- **Drag and drop**: Lift effect (shadow and scale), drop zone highlights, smooth repositioning
86
-
- **Copy or paste**: Brief highlight flash on paste, "copied" confirmation
87
-
- **Focus flow**: Highlight path through form or workflow
88
-
89
-
### Delight Moments
90
-
- **Empty states**: Subtle floating animations on illustrations
91
-
- **Completed actions**: Confetti, check mark flourish, success celebrations
92
-
- **Easter eggs**: Hidden interactions for discovery
93
-
- **Contextual animation**: Weather effects, time-of-day themes, seasonal touches
94
-
95
-
## Technical Implementation
96
-
97
-
Use appropriate techniques for each animation.
98
-
99
-
### Timing and Easing
100
-
101
-
**Durations by purpose:**
102
-
- **100-150ms**: Instant feedback (button press, toggle)
103
-
- **200-300ms**: State changes (hover, menu open)
104
-
- **300-500ms**: Layout changes (accordion, modal)
105
-
- **500-800ms**: Entrance animations (page load)
106
-
107
-
**Easing curves (use these, not CSS defaults):**
108
-
```css
109
-
/* Recommended - natural deceleration */
110
-
--ease-out-quart: cubic-bezier(0.25, 1, 0.5, 1); /* Smooth, refined */
111
-
--ease-out-quint: cubic-bezier(0.22, 1, 0.36, 1); /* Slightly snappier */
112
-
--ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1); /* Confident, decisive */
113
-
114
-
/* AVOID - feel dated and tacky */
115
-
/* bounce: cubic-bezier(0.34, 1.56, 0.64, 1); */
116
-
/* elastic: cubic-bezier(0.68, -0.6, 0.32, 1.6); */
117
-
```
118
-
119
-
**Exit animations are faster than entrances.** Use approximately 75% of enter duration.
120
-
121
-
### CSS Animations
122
-
```css
123
-
/* Prefer for simple, declarative animations */
124
-
- transitions for state changes
125
-
- @keyframes for complex sequences
126
-
- transform and opacity only (GPU-accelerated)
127
-
```
128
-
129
-
### JavaScript Animation
130
-
```javascript
131
-
/* Use for complex, interactive animations */
132
-
- Web Animations API for programmatic control
133
-
- Framer Motion for React
134
-
- GSAP for complex sequences
135
-
```
136
-
137
-
### Performance
138
-
- **GPU acceleration**: Use transform and opacity, avoid layout properties
139
-
- **will-change**: Add sparingly for known expensive animations
140
-
- **Reduce paint**: Minimize repaints, use contain where appropriate
141
-
- **Monitor FPS**: Ensure 60fps on target devices
142
-
143
-
### Accessibility
144
-
```css
145
-
@media (prefers-reduced-motion: reduce) {
146
-
* {
147
-
animation-duration: 0.01ms !important;
148
-
animation-iteration-count: 1 !important;
149
-
transition-duration: 0.01ms !important;
150
-
}
151
-
}
152
-
```
153
-
154
-
**NEVER**:
155
-
- Use bounce or elastic easing curves. They feel dated and draw attention to the animation itself.
156
-
- Animate layout properties (width, height, top, left). Use transform instead.
157
-
- Use durations over 500ms for feedback. It feels laggy.
158
-
- Animate without purpose. Every animation needs a reason.
159
-
- Ignore prefers-reduced-motion. This is an accessibility violation.
160
-
- Animate everything. Animation fatigue makes interfaces feel exhausting.
161
-
- Block interaction during animations unless intentional.
162
-
163
-
## Verify Quality
164
-
165
-
Test animations thoroughly.
166
-
167
-
- **Smooth at 60fps**: No jank on target devices
168
-
- **Feels natural**: Easing curves feel organic, not robotic
169
-
- **Appropriate timing**: Not too fast (jarring) or too slow (laggy)
170
-
- **Reduced motion works**: Animations disabled or simplified appropriately
171
-
- **Does not block**: Users can interact during or after animations
172
-
- **Adds value**: Makes interface clearer or more delightful
173
-
174
-
Remember: Motion should enhance understanding and provide feedback, not just add decoration. Animate with purpose, respect performance constraints, and always consider accessibility. Great animation is invisible. It just makes everything feel right.
+7
-7
skills/arrange/SKILL.md
+7
-7
skills/arrange/SKILL.md
···
1
1
---
2
2
name: arrange
3
-
description: "Improve layout, spacing, and visual rhythm. Fixes monotonous grids, inconsistent spacing, and weak visual hierarchy. Use when the user mentions layout feeling off, spacing issues, visual hierarchy, crowded UI, alignment problems, or wanting better composition."
3
+
description: "Improve layout, spacing, and visual rhythm. Fixes monotonous grids, inconsistent spacing, and weak visual hierarchy. Use when user mentions layout feeling off, spacing issues, visual hierarchy, crowded UI, alignment problems, or wanting better composition."
4
4
argument-hint: "[target]"
5
5
user-invocable: true
6
6
---
···
9
9
10
10
## MANDATORY PREPARATION
11
11
12
-
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first.
12
+
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and Context Gathering Protocol. Follow protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first.
13
13
14
14
---
15
15
16
16
## Assess Current Layout
17
17
18
-
Analyze what is weak about the current spatial design.
18
+
Analyze what is weak about current spatial design.
19
19
20
20
### 1. Spacing
21
21
- Is spacing consistent or arbitrary? (Random padding or margin values)
···
42
42
- Is layout too sparse? (Excessive whitespace without purpose)
43
43
- Does density match content type? (Data-dense UIs need tighter spacing; marketing pages need more air)
44
44
45
-
**CRITICAL**: Layout problems are often the root cause of interfaces feeling "off" even when colors and fonts are fine. Space is a design material. Use it with intention.
45
+
**CRITICAL**: Layout problems are often root cause of interfaces feeling "off" even when colors and fonts are fine. Space is design material. Use it with intention.
46
46
47
47
## Plan Layout Improvements
48
48
49
-
Consult the [spatial design reference](reference/spatial-design.md) from the frontend-design skill for detailed guidance on grids, rhythm, and container queries.
49
+
Consult [spatial design reference](reference/spatial-design.md) from frontend-design skill for detailed guidance on grids, rhythm, and container queries.
50
50
51
-
Create a systematic plan.
51
+
Create systematic plan.
52
52
53
53
- **Spacing system**: Use consistent scale. Whether that is framework built-in scale (e.g., Tailwind), rem-based tokens, or custom system. specific values matter less than consistency.
54
54
- **Hierarchy strategy**: How will space communicate importance?
···
121
121
- **Consistency**: Is spacing system applied uniformly?
122
122
- **Responsiveness**: Does layout adapt gracefully across screen sizes?
123
123
124
-
Remember: Space is the most underused design tool. A layout with the right rhythm and hierarchy can make even simple content feel polished and intentional.
124
+
Remember: Space is most underused design tool. layout with right rhythm and hierarchy can make even simple content feel polished and intentional.
-124
skills/arrange/SKILL.md.original.md
-124
skills/arrange/SKILL.md.original.md
···
1
-
---
2
-
name: arrange
3
-
description: "Improve layout, spacing, and visual rhythm. Fixes monotonous grids, inconsistent spacing, and weak visual hierarchy. Use when the user mentions layout feeling off, spacing issues, visual hierarchy, crowded UI, alignment problems, or wanting better composition."
4
-
argument-hint: "[target]"
5
-
user-invocable: true
6
-
---
7
-
8
-
Assess and improve layout and spacing that feels monotonous, crowded, or structurally weak. Turn generic arrangements into intentional, rhythmic compositions.
9
-
10
-
## MANDATORY PREPARATION
11
-
12
-
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first.
13
-
14
-
---
15
-
16
-
## Assess Current Layout
17
-
18
-
Analyze what is weak about the current spatial design.
19
-
20
-
### 1. Spacing
21
-
- Is spacing consistent or arbitrary? (Random padding or margin values)
22
-
- Is all spacing the same? (Equal padding everywhere equals no rhythm)
23
-
- Are related elements grouped tightly, with generous space between groups?
24
-
25
-
### 2. Visual hierarchy
26
-
- Apply the squint test: blur your (metaphorical) eyes. Can you still identify the most important element, second most important, and clear groupings?
27
-
- Is hierarchy achieved effectively? (Space and weight alone can be enough. But is the current approach working?)
28
-
- Does whitespace guide the eye to what matters?
29
-
30
-
### 3. Grid and structure
31
-
- Is there a clear underlying structure, or does the layout feel random?
32
-
- Are identical card grids used everywhere? (Icon plus heading plus text, repeated endlessly)
33
-
- Is everything centered? (Left-aligned with asymmetric layouts feels more designed, but not a hard and fast rule)
34
-
35
-
### 4. Rhythm and variety
36
-
- Does the layout have visual rhythm? (Alternating tight or generous spacing)
37
-
- Is every section structured the same way? (Monotonous repetition)
38
-
- Are there intentional moments of surprise or emphasis?
39
-
40
-
### 5. Density
41
-
- Is the layout too cramped? (Not enough breathing room)
42
-
- Is the layout too sparse? (Excessive whitespace without purpose)
43
-
- Does density match the content type? (Data-dense UIs need tighter spacing; marketing pages need more air)
44
-
45
-
**CRITICAL**: Layout problems are often the root cause of interfaces feeling "off" even when colors and fonts are fine. Space is a design material. Use it with intention.
46
-
47
-
## Plan Layout Improvements
48
-
49
-
Consult the [spatial design reference](reference/spatial-design.md) from the frontend-design skill for detailed guidance on grids, rhythm, and container queries.
50
-
51
-
Create a systematic plan.
52
-
53
-
- **Spacing system**: Use a consistent scale. Whether that is a framework built-in scale (e.g., Tailwind), rem-based tokens, or a custom system. The specific values matter less than consistency.
54
-
- **Hierarchy strategy**: How will space communicate importance?
55
-
- **Layout approach**: What structure fits the content? Flex for 1D, Grid for 2D, named areas for complex page layouts.
56
-
- **Rhythm**: Where should spacing be tight vs generous?
57
-
58
-
## Improve Layout Systematically
59
-
60
-
### Establish a Spacing System
61
-
62
-
- Use a consistent spacing scale. Framework scales (Tailwind, etc.), rem-based tokens, or a custom scale all work. What matters is that values come from a defined set, not arbitrary numbers.
63
-
- Name tokens semantically if using custom properties: --space-xs through --space-xl, not --spacing-8
64
-
- Use gap for sibling spacing instead of margins. Eliminates margin collapse hacks.
65
-
- Apply clamp() for fluid spacing that breathes on larger screens.
66
-
67
-
### Create Visual Rhythm
68
-
69
-
- **Tight grouping** for related elements (8-12px between siblings)
70
-
- **Generous separation** between distinct sections (48-96px)
71
-
- **Varied spacing** within sections. Not every row needs the same gap.
72
-
- **Asymmetric compositions**. Break the predictable centered-content pattern when it makes sense.
73
-
74
-
### Choose the Right Layout Tool
75
-
76
-
- **Use Flexbox for 1D layouts**: Rows of items, nav bars, button groups, card contents, most component internals. Flex is simpler and more appropriate for the majority of layout tasks.
77
-
- **Use Grid for 2D layouts**: Page-level structure, dashboards, data-dense interfaces, anything where rows AND columns need coordinated control.
78
-
- **Do not default to Grid** when Flexbox with flex-wrap would be simpler and more flexible.
79
-
- Use repeat(auto-fit, minmax(280px, 1fr)) for responsive grids without breakpoints.
80
-
- Use named grid areas (grid-template-areas) for complex page layouts. Redefine at breakpoints.
81
-
82
-
### Break Card Grid Monotony
83
-
84
-
- Do not default to card grids for everything. Spacing and alignment create visual grouping naturally.
85
-
- Use cards only when content is truly distinct and actionable. Never nest cards inside cards.
86
-
- Vary card sizes, span columns, or mix cards with non-card content to break repetition.
87
-
88
-
### Strengthen Visual Hierarchy
89
-
90
-
- Use the fewest dimensions needed for clear hierarchy. Space alone can be enough. Generous whitespace around an element draws the eye. Some of the most sophisticated designs achieve rhythm with just space and weight. Add color or size contrast only when simpler means are not sufficient.
91
-
- Be aware of reading flow. In LTR languages, the eye naturally scans top-left to bottom-right, but primary action placement depends on context (e.g., bottom-right in dialogs, top in navigation).
92
-
- Create clear content groupings through proximity and separation.
93
-
94
-
### Manage Depth and Elevation
95
-
96
-
- Create a semantic z-index scale (dropdown, sticky, modal-backdrop, modal, toast, tooltip)
97
-
- Build a consistent shadow scale (sm, md, lg, xl). Shadows should be subtle.
98
-
- Use elevation to reinforce hierarchy, not as decoration.
99
-
100
-
### Optical Adjustments
101
-
102
-
- If an icon looks visually off-center despite being geometrically centered, nudge it. But only if you are confident it actually looks wrong. Do not adjust speculatively.
103
-
104
-
**NEVER**:
105
-
- Use arbitrary spacing values outside your scale
106
-
- Make all spacing equal. Variety creates hierarchy.
107
-
- Wrap everything in cards. Not everything needs a container.
108
-
- Nest cards inside cards. Use spacing and dividers for hierarchy within.
109
-
- Use identical card grids everywhere (icon plus heading plus text, repeated)
110
-
- Center everything. Left-aligned with asymmetry feels more designed.
111
-
- Default to the hero metric layout (big number, small label, stats, gradient) as a template. If showing real user data, a prominent metric can work. But it should display actual data, not decorative numbers.
112
-
- Default to CSS Grid when Flexbox would be simpler. Use the simplest tool for the job.
113
-
- Use arbitrary z-index values (999, 9999). Build a semantic scale.
114
-
115
-
## Verify Layout Improvements
116
-
117
-
- **Squint test**: Can you identify primary, secondary, and groupings with blurred vision?
118
-
- **Rhythm**: Does the page have a satisfying beat of tight and generous spacing?
119
-
- **Hierarchy**: Is the most important content obvious within 2 seconds?
120
-
- **Breathing room**: Does the layout feel comfortable, not cramped or wasteful?
121
-
- **Consistency**: Is the spacing system applied uniformly?
122
-
- **Responsiveness**: Does the layout adapt gracefully across screen sizes?
123
-
124
-
Remember: Space is the most underused design tool. A layout with the right rhythm and hierarchy can make even simple content feel polished and intentional.
+12
-12
skills/audit/SKILL.md
+12
-12
skills/audit/SKILL.md
···
1
1
---
2
2
name: audit
3
-
description: "Run technical quality checks across accessibility, performance, theming, responsive design, and anti-patterns. Generates a scored report with P0-P3 severity ratings and actionable plan. Use when the user wants an accessibility check, performance audit, or technical quality review."
3
+
description: "Run technical quality checks across accessibility, performance, theming, responsive design, and anti-patterns. Generates scored report with P0-P3 severity ratings and actionable plan. Use when user wants accessibility check, performance audit, or technical quality review."
4
4
argument-hint: "[area (feature, page, component...)]"
5
5
user-invocable: true
6
6
---
7
7
8
8
## MANDATORY PREPARATION
9
9
10
-
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first.
10
+
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and Context Gathering Protocol. Follow protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first.
11
11
12
12
---
13
13
14
-
Run systematic technical quality checks and generate a comprehensive report. Do not fix issues. Document them for other commands to address.
14
+
Run systematic technical quality checks and generate comprehensive report. Do not fix issues. Document them for other commands to address.
15
15
16
-
This is a code-level audit, not a design critique. Check what is measurable and verifiable in the implementation.
16
+
This is code-level audit, not design critique. Check what is measurable and verifiable in implementation.
17
17
18
18
## Diagnostic Scan
19
19
20
-
Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the criteria below.
20
+
Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using criteria below.
21
21
22
22
### 1. Accessibility (A11y)
23
23
···
29
29
- **Alt text**: Missing or poor image descriptions
30
30
- **Form issues**: Inputs without labels, poor error messaging, missing required indicators
31
31
32
-
**Score 0-4**: 0=Inaccessible (fails WCAG A), 1=Major gaps (few ARIA labels, no keyboard nav), 2=Partial (some a11y effort, significant gaps), 3=Good (WCAG AA mostly met, minor gaps), 4=Excellent (WCAG AA fully met, approaches AAA)
32
+
**Score 0-4**: 0=Inaccessible (fails WCAG ), 1=Major gaps (few ARIA labels, no keyboard nav), 2=Partial (some a11y effort, significant gaps), 3=Good (WCAG AA mostly met, minor gaps), 4=Excellent (WCAG AA fully met, approaches AAA)
33
33
34
34
### 2. Performance
35
35
···
65
65
66
66
### 5. Anti-Patterns (CRITICAL)
67
67
68
-
Check against ALL the DO NOT guidelines in the frontend-design skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy).
68
+
Check against ALL DO NOT guidelines in frontend-design skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy).
69
69
70
70
**Score 0-4**: 0=AI slop gallery (5+ tells), 1=Heavy AI aesthetic (3-4 tells), 2=Some tells (1-2 noticeable), 3=Mostly clean (subtle issues only), 4=No AI tells (distinctive, intentional design)
71
71
···
88
88
**Start here.** Pass or fail: Does this look AI-generated? List specific tells. Be brutally honest.
89
89
90
90
### Executive Summary
91
-
- Audit Health Score: ??/20 (rating band)
91
+
- Audit Health Score:??/20 (rating band)
92
92
- Total issues found (count by severity: P0/P1/P2/P3)
93
93
- Top 3-5 critical issues
94
94
- Recommended next steps
···
127
127
1. **[P?] `{{command_prefix}}command-name`**: Brief description (specific context from audit findings)
128
128
2. **[P?] `{{command_prefix}}command-name`**: Brief description (specific context)
129
129
130
-
**Rules**: Only recommend commands from: {{available_commands}}. Map findings to the most appropriate command. End with {{command_prefix}}polish as the final step if any fixes were recommended.
130
+
**Rules**: Only recommend commands from: {{available_commands}}. Map findings to most appropriate command. End with {{command_prefix}}polish as final step if any fixes were recommended.
131
131
132
-
After presenting the summary, tell the user:
132
+
After presenting summary, tell user:
133
133
134
-
> You can ask me to run these one at a time, all at once, or in any order you prefer.
134
+
> ask me to run these one at time, all at once, or in any order you prefer.
135
135
>
136
136
> Re-run {{command_prefix}}audit after fixes to see your score improve.
137
137
···
144
144
- Forget to prioritize (everything cannot be P0)
145
145
- Report false positives without verification
146
146
147
-
Remember: You are a technical quality auditor. Document systematically, prioritize ruthlessly, cite specific code locations, and provide clear paths to improvement.
147
+
Remember: You are technical quality auditor. Document systematically, prioritize ruthlessly, cite specific code locations, and provide clear paths to improvement.
-147
skills/audit/SKILL.md.original.md
-147
skills/audit/SKILL.md.original.md
···
1
-
---
2
-
name: audit
3
-
description: "Run technical quality checks across accessibility, performance, theming, responsive design, and anti-patterns. Generates a scored report with P0-P3 severity ratings and actionable plan. Use when the user wants an accessibility check, performance audit, or technical quality review."
4
-
argument-hint: "[area (feature, page, component...)]"
5
-
user-invocable: true
6
-
---
7
-
8
-
## MANDATORY PREPARATION
9
-
10
-
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first.
11
-
12
-
---
13
-
14
-
Run systematic technical quality checks and generate a comprehensive report. Do not fix issues. Document them for other commands to address.
15
-
16
-
This is a code-level audit, not a design critique. Check what is measurable and verifiable in the implementation.
17
-
18
-
## Diagnostic Scan
19
-
20
-
Run comprehensive checks across 5 dimensions. Score each dimension 0-4 using the criteria below.
21
-
22
-
### 1. Accessibility (A11y)
23
-
24
-
**Check for**:
25
-
- **Contrast issues**: Text contrast ratios less than 4.5:1 (or 7:1 for AAA)
26
-
- **Missing ARIA**: Interactive elements without proper roles, labels, or states
27
-
- **Keyboard navigation**: Missing focus indicators, illogical tab order, keyboard traps
28
-
- **Semantic HTML**: Improper heading hierarchy, missing landmarks, divs instead of buttons
29
-
- **Alt text**: Missing or poor image descriptions
30
-
- **Form issues**: Inputs without labels, poor error messaging, missing required indicators
31
-
32
-
**Score 0-4**: 0=Inaccessible (fails WCAG A), 1=Major gaps (few ARIA labels, no keyboard nav), 2=Partial (some a11y effort, significant gaps), 3=Good (WCAG AA mostly met, minor gaps), 4=Excellent (WCAG AA fully met, approaches AAA)
33
-
34
-
### 2. Performance
35
-
36
-
**Check for**:
37
-
- **Layout thrashing**: Reading or writing layout properties in loops
38
-
- **Expensive animations**: Animating layout properties (width, height, top, left) instead of transform or opacity
39
-
- **Missing optimization**: Images without lazy loading, unoptimized assets, missing will-change
40
-
- **Bundle size**: Unnecessary imports, unused dependencies
41
-
- **Render performance**: Unnecessary re-renders, missing memoization
42
-
43
-
**Score 0-4**: 0=Severe issues (layout thrash, unoptimized everything), 1=Major problems (no lazy loading, expensive animations), 2=Partial (some optimization, gaps remain), 3=Good (mostly optimized, minor improvements possible), 4=Excellent (fast, lean, well-optimized)
44
-
45
-
### 3. Theming
46
-
47
-
**Check for**:
48
-
- **Hard-coded colors**: Colors not using design tokens
49
-
- **Broken dark mode**: Missing dark mode variants, poor contrast in dark theme
50
-
- **Inconsistent tokens**: Using wrong tokens, mixing token types
51
-
- **Theme switching issues**: Values that do not update on theme change
52
-
53
-
**Score 0-4**: 0=No theming (hard-coded everything), 1=Minimal tokens (mostly hard-coded), 2=Partial (tokens exist but inconsistently used), 3=Good (tokens used, minor hard-coded values), 4=Excellent (full token system, dark mode works perfectly)
54
-
55
-
### 4. Responsive Design
56
-
57
-
**Check for**:
58
-
- **Fixed widths**: Hard-coded widths that break on mobile
59
-
- **Touch targets**: Interactive elements less than 44x44px
60
-
- **Horizontal scroll**: Content overflow on narrow viewports
61
-
- **Text scaling**: Layouts that break when text size increases
62
-
- **Missing breakpoints**: No mobile or tablet variants
63
-
64
-
**Score 0-4**: 0=Desktop-only (breaks on mobile), 1=Major issues (some breakpoints, many failures), 2=Partial (works on mobile, rough edges), 3=Good (responsive, minor touch target or overflow issues), 4=Excellent (fluid, all viewports, proper touch targets)
65
-
66
-
### 5. Anti-Patterns (CRITICAL)
67
-
68
-
Check against ALL the DO NOT guidelines in the frontend-design skill. Look for AI slop tells (AI color palette, gradient text, glassmorphism, hero metrics, card grids, generic fonts) and general design anti-patterns (gray on color, nested cards, bounce easing, redundant copy).
69
-
70
-
**Score 0-4**: 0=AI slop gallery (5+ tells), 1=Heavy AI aesthetic (3-4 tells), 2=Some tells (1-2 noticeable), 3=Mostly clean (subtle issues only), 4=No AI tells (distinctive, intentional design)
71
-
72
-
## Generate Report
73
-
74
-
### Audit Health Score
75
-
76
-
| # | Dimension | Score | Key Finding |
77
-
|---|-----------|-------|-------------|
78
-
| 1 | Accessibility | ? | [most critical a11y issue or "--"] |
79
-
| 2 | Performance | ? | |
80
-
| 3 | Responsive Design | ? | |
81
-
| 4 | Theming | ? | |
82
-
| 5 | Anti-Patterns | ? | |
83
-
| **Total** | | **??/20** | **[Rating band]** |
84
-
85
-
**Rating bands**: 18-20 Excellent (minor polish), 14-17 Good (address weak dimensions), 10-13 Acceptable (significant work needed), 6-9 Poor (major overhaul), 0-5 Critical (fundamental issues)
86
-
87
-
### Anti-Patterns Verdict
88
-
**Start here.** Pass or fail: Does this look AI-generated? List specific tells. Be brutally honest.
89
-
90
-
### Executive Summary
91
-
- Audit Health Score: ??/20 (rating band)
92
-
- Total issues found (count by severity: P0/P1/P2/P3)
93
-
- Top 3-5 critical issues
94
-
- Recommended next steps
95
-
96
-
### Detailed Findings by Severity
97
-
98
-
Tag every issue with P0-P3 severity:
99
-
- **P0 Blocking**: Prevents task completion. Fix immediately.
100
-
- **P1 Major**: Significant difficulty or WCAG AA violation. Fix before release.
101
-
- **P2 Minor**: Annoyance, workaround exists. Fix in next pass.
102
-
- **P3 Polish**: Nice-to-fix, no real user impact. Fix if time permits.
103
-
104
-
For each issue, document:
105
-
- **[P?] Issue name**
106
-
- **Location**: Component, file, line
107
-
- **Category**: Accessibility, Performance, Theming, Responsive, or Anti-Pattern
108
-
- **Impact**: How it affects users
109
-
- **WCAG or Standard**: Which standard it violates (if applicable)
110
-
- **Recommendation**: How to fix it
111
-
- **Suggested command**: Which command to use (prefer: {{available_commands}})
112
-
113
-
### Patterns and Systemic Issues
114
-
115
-
Identify recurring problems that indicate systemic gaps rather than one-off mistakes:
116
-
- "Hard-coded colors appear in 15+ components, should use design tokens"
117
-
- "Touch targets consistently too small (less than 44px) throughout mobile experience"
118
-
119
-
### Positive Findings
120
-
121
-
Note what is working well. Good practices to maintain and replicate.
122
-
123
-
## Recommended Actions
124
-
125
-
List recommended commands in priority order (P0 first, then P1, then P2):
126
-
127
-
1. **[P?] `{{command_prefix}}command-name`**: Brief description (specific context from audit findings)
128
-
2. **[P?] `{{command_prefix}}command-name`**: Brief description (specific context)
129
-
130
-
**Rules**: Only recommend commands from: {{available_commands}}. Map findings to the most appropriate command. End with {{command_prefix}}polish as the final step if any fixes were recommended.
131
-
132
-
After presenting the summary, tell the user:
133
-
134
-
> You can ask me to run these one at a time, all at once, or in any order you prefer.
135
-
>
136
-
> Re-run {{command_prefix}}audit after fixes to see your score improve.
137
-
138
-
**IMPORTANT**: Be thorough but actionable. Too many P3 issues creates noise. Focus on what actually matters.
139
-
140
-
**NEVER**:
141
-
- Report issues without explaining impact (why does this matter?)
142
-
- Provide generic recommendations (be specific and actionable)
143
-
- Skip positive findings (celebrate what works)
144
-
- Forget to prioritize (everything cannot be P0)
145
-
- Report false positives without verification
146
-
147
-
Remember: You are a technical quality auditor. Document systematically, prioritize ruthlessly, cite specific code locations, and provide clear paths to improvement.
+8
-8
skills/bolder/SKILL.md
+8
-8
skills/bolder/SKILL.md
···
1
1
---
2
2
name: bolder
3
-
description: "Amplify safe or boring designs to make them more visually interesting and stimulating. Increases impact while maintaining usability. Use when the user says the design looks bland, generic, too safe, lacks personality, or wants more visual impact and character."
3
+
description: "Amplify safe or boring designs to make them more visually interesting and stimulating. Increases impact while maintaining usability. Use when user says design looks bland, generic, too safe, lacks personality, or wants more visual impact and character."
4
4
argument-hint: "[target]"
5
5
user-invocable: true
6
6
---
···
9
9
10
10
## MANDATORY PREPARATION
11
11
12
-
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first.
12
+
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and Context Gathering Protocol. Follow protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first.
13
13
14
14
---
15
15
16
16
## Assess Current State
17
17
18
-
Analyze what makes the design feel too safe or boring.
18
+
Analyze what makes design feel too safe or boring.
19
19
20
20
### 1. Identify weakness sources
21
21
- **Generic choices**: System fonts, basic colors, standard layouts
···
31
31
- Who is audience? (What will resonate?)
32
32
- What are constraints? (Brand guidelines, accessibility, performance)
33
33
34
-
If any of these are unclear from the codebase, {{ask_instruction}}
34
+
If any of these are unclear from codebase, {{ask_instruction}}
35
35
36
36
**CRITICAL**: "Bolder" does not mean chaotic or garish. It means distinctive, memorable, and confident. Think intentional drama, not random chaos.
37
37
38
-
**WARNING - AI SLOP TRAP**: When making things "bolder," AI defaults to the same tired tricks: cyan or purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the OPPOSITE of bold. They are generic. Review ALL the DO NOT guidelines in the frontend-design skill before proceeding. Bold means distinctive, not "more effects."
38
+
**WARNING - AI SLOP TRAP**: When making things "bolder," AI defaults to same tired tricks: cyan or purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are OPPOSITE of bold. They are generic. Review ALL DO NOT guidelines in frontend-design skill before proceeding. Bold means distinctive, not "more effects."
39
39
40
40
## Plan Amplification
41
41
42
-
Create a strategy to increase impact while maintaining coherence.
42
+
Create strategy to increase impact while maintaining coherence.
43
43
44
44
- **Focal point**: What should be hero moment? (Pick ONE, make it amazing)
45
45
- **Personality direction**: Maximalist chaos? Elegant drama? Playful energy? Dark moody? Choose lane.
···
76
76
### Visual Effects
77
77
- **Dramatic shadows**: Large, soft shadows for elevation (but not generic drop shadows on rounded rectangles)
78
78
- **Background treatments**: Mesh patterns, noise textures, geometric patterns, intentional gradients (not purple-to-blue)
79
-
- **Texture and depth**: Grain, halftone, duotone, layered elements. NOT glassmorphism (it is overused AI slop).
79
+
- **Texture and depth**: Grain, halftone, duotone, layered elements. NOT glassmorphism (it's overused AI slop).
80
80
- **Borders and frames**: Thick borders, decorative frames, custom shapes (not rounded rectangles with colored border on one side)
81
81
- **Custom elements**: Illustrative elements, custom icons, decorative details that reinforce brand
82
82
···
111
111
- **Performant**: Do all these effects run smoothly?
112
112
- **Accessible**: Does it still meet accessibility standards?
113
113
114
-
**The test**: If you showed this to someone and said "AI made this bolder," would they believe you immediately? If yes, you have failed. Bold means distinctive, not "more AI effects."
114
+
** test**: If you showed this to someone and said "AI made this bolder," would they believe you immediately? If yes, you have failed. Bold means distinctive, not "more AI effects."
115
115
116
116
Remember: Bold design is confident design. It takes risks, makes statements, and creates memorable experiences. But bold without strategy is loud. Be intentional, be dramatic, be unforgettable.
-116
skills/bolder/SKILL.md.original.md
-116
skills/bolder/SKILL.md.original.md
···
1
-
---
2
-
name: bolder
3
-
description: "Amplify safe or boring designs to make them more visually interesting and stimulating. Increases impact while maintaining usability. Use when the user says the design looks bland, generic, too safe, lacks personality, or wants more visual impact and character."
4
-
argument-hint: "[target]"
5
-
user-invocable: true
6
-
---
7
-
8
-
Increase visual impact and personality in designs that are too safe, generic, or visually underwhelming, creating more engaging and memorable experiences.
9
-
10
-
## MANDATORY PREPARATION
11
-
12
-
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first.
13
-
14
-
---
15
-
16
-
## Assess Current State
17
-
18
-
Analyze what makes the design feel too safe or boring.
19
-
20
-
### 1. Identify weakness sources
21
-
- **Generic choices**: System fonts, basic colors, standard layouts
22
-
- **Timid scale**: Everything is medium-sized with no drama
23
-
- **Low contrast**: Everything has similar visual weight
24
-
- **Static**: No motion, no energy, no life
25
-
- **Predictable**: Standard patterns with no surprises
26
-
- **Flat hierarchy**: Nothing stands out or commands attention
27
-
28
-
### 2. Understand the context
29
-
- What is the brand personality? (How far can we push?)
30
-
- What is the purpose? (Marketing can be bolder than financial dashboards)
31
-
- Who is the audience? (What will resonate?)
32
-
- What are the constraints? (Brand guidelines, accessibility, performance)
33
-
34
-
If any of these are unclear from the codebase, {{ask_instruction}}
35
-
36
-
**CRITICAL**: "Bolder" does not mean chaotic or garish. It means distinctive, memorable, and confident. Think intentional drama, not random chaos.
37
-
38
-
**WARNING - AI SLOP TRAP**: When making things "bolder," AI defaults to the same tired tricks: cyan or purple gradients, glassmorphism, neon accents on dark backgrounds, gradient text on metrics. These are the OPPOSITE of bold. They are generic. Review ALL the DO NOT guidelines in the frontend-design skill before proceeding. Bold means distinctive, not "more effects."
39
-
40
-
## Plan Amplification
41
-
42
-
Create a strategy to increase impact while maintaining coherence.
43
-
44
-
- **Focal point**: What should be the hero moment? (Pick ONE, make it amazing)
45
-
- **Personality direction**: Maximalist chaos? Elegant drama? Playful energy? Dark moody? Choose a lane.
46
-
- **Risk budget**: How experimental can we be? Push boundaries within constraints.
47
-
- **Hierarchy amplification**: Make big things BIGGER, small things smaller (increase contrast)
48
-
49
-
**IMPORTANT**: Bold design must still be usable. Impact without function is just decoration.
50
-
51
-
## Amplify the Design
52
-
53
-
Systematically increase impact across these dimensions.
54
-
55
-
### Typography Amplification
56
-
- **Replace generic fonts**: Swap system fonts for distinctive choices (see frontend-design skill for inspiration)
57
-
- **Extreme scale**: Create dramatic size jumps (3x-5x differences, not 1.5x)
58
-
- **Weight contrast**: Pair 900 weights with 200 weights, not 600 with 400
59
-
- **Unexpected choices**: Variable fonts, display fonts for headlines, condensed or extended widths, monospace as intentional accent (not as lazy "dev tool" default)
60
-
61
-
### Color Intensification
62
-
- **Increase saturation**: Shift to more vibrant, energetic colors (but not neon)
63
-
- **Bold palette**: Introduce unexpected color combinations. Avoid the purple-blue gradient AI slop.
64
-
- **Dominant color strategy**: Let one bold color own 60% of the design
65
-
- **Sharp accents**: High-contrast accent colors that pop
66
-
- **Tinted neutrals**: Replace pure grays with tinted grays that harmonize with your palette
67
-
- **Rich gradients**: Intentional multi-stop gradients (not generic purple-to-blue)
68
-
69
-
### Spatial Drama
70
-
- **Extreme scale jumps**: Make important elements 3-5x larger than surroundings
71
-
- **Break the grid**: Let hero elements escape containers and cross boundaries
72
-
- **Asymmetric layouts**: Replace centered, balanced layouts with tension-filled asymmetry
73
-
- **Generous space**: Use white space dramatically (100-200px gaps, not 20-40px)
74
-
- **Overlap**: Layer elements intentionally for depth
75
-
76
-
### Visual Effects
77
-
- **Dramatic shadows**: Large, soft shadows for elevation (but not generic drop shadows on rounded rectangles)
78
-
- **Background treatments**: Mesh patterns, noise textures, geometric patterns, intentional gradients (not purple-to-blue)
79
-
- **Texture and depth**: Grain, halftone, duotone, layered elements. NOT glassmorphism (it is overused AI slop).
80
-
- **Borders and frames**: Thick borders, decorative frames, custom shapes (not rounded rectangles with colored border on one side)
81
-
- **Custom elements**: Illustrative elements, custom icons, decorative details that reinforce brand
82
-
83
-
### Motion and Animation
84
-
- **Entrance choreography**: Staggered, dramatic page load animations with 50-100ms delays
85
-
- **Scroll effects**: Parallax, reveal animations, scroll-triggered sequences
86
-
- **Micro-interactions**: Satisfying hover effects, click feedback, state changes
87
-
- **Transitions**: Smooth, noticeable transitions using ease-out-quart, quint, or expo (not bounce or elastic. They cheapen the effect.)
88
-
89
-
### Composition Boldness
90
-
- **Hero moments**: Create clear focal points with dramatic treatment
91
-
- **Diagonal flows**: Escape horizontal or vertical rigidity with diagonal arrangements
92
-
- **Full-bleed elements**: Use full viewport width or height for impact
93
-
- **Unexpected proportions**: Golden ratio? Throw it out. Try 70-30, 80-20 splits.
94
-
95
-
**NEVER**:
96
-
- Add effects randomly without purpose (chaos does not equal bold)
97
-
- Sacrifice readability for aesthetics (body text must be readable)
98
-
- Make everything bold (then nothing is bold. Need contrast.)
99
-
- Ignore accessibility (bold design must still meet WCAG standards)
100
-
- Overwhelm with motion (animation fatigue is real)
101
-
- Copy trendy aesthetics blindly (bold means distinctive, not derivative)
102
-
103
-
## Verify Quality
104
-
105
-
Ensure amplification maintains usability and coherence.
106
-
107
-
- **NOT AI slop**: Does this look like every other AI-generated "bold" design? If yes, start over.
108
-
- **Still functional**: Can users accomplish tasks without distraction?
109
-
- **Coherent**: Does everything feel intentional and unified?
110
-
- **Memorable**: Will users remember this experience?
111
-
- **Performant**: Do all these effects run smoothly?
112
-
- **Accessible**: Does it still meet accessibility standards?
113
-
114
-
**The test**: If you showed this to someone and said "AI made this bolder," would they believe you immediately? If yes, you have failed. Bold means distinctive, not "more AI effects."
115
-
116
-
Remember: Bold design is confident design. It takes risks, makes statements, and creates memorable experiences. But bold without strategy is just loud. Be intentional, be dramatic, be unforgettable.
+14
-15
skills/cavecrew/SKILL.md
+14
-15
skills/cavecrew/SKILL.md
···
1
1
---
2
2
name: cavecrew
3
3
description: >
4
-
Decision guide for delegating to caveman-style subagents. Tells the main
5
-
thread WHEN to spawn `cavecrew-investigator` (locate code), `cavecrew-builder`
6
-
(1-2 file edit), or `cavecrew-reviewer` (diff review) instead of doing the
7
-
work inline or using vanilla `Explore`. Subagent output is caveman-compressed
8
-
so the tool-result injected back into main context is ~60% smaller — main
9
-
context lasts longer across long sessions.
10
-
Trigger: "delegate to subagent", "use cavecrew", "spawn investigator/builder/reviewer",
11
-
"save context", "compressed agent output".
4
+
Decision guide for delegating to caveman-style subagents. Tells main
5
+
thread WHEN to spawn `cavecrew-investigator` (locate code), `cavecrew-builder`
6
+
(1-2 file edit), or `cavecrew-reviewer` (diff review) instead of doing work inline or using vanilla `Explore`. Subagent output is caveman-compressed
7
+
so tool-result injected back into main context is ~60% smaller — main
8
+
context lasts longer across long sessions.
9
+
Trigger: "delegate to subagent", "use cavecrew", "spawn investigator/builder/reviewer",
10
+
"save context", "compressed agent output".
12
11
---
13
12
14
-
Cavecrew = three subagent presets that emit caveman output. Same job as Anthropic defaults (`Explore`, edit-style agents, reviewer); difference is the tool-result they return is compressed, so main context shrinks per delegation.
13
+
Cavecrew = three subagent presets that emit caveman output. Same job as Anthropic defaults (`Explore`, edit-style agents, reviewer); difference is tool-result they return is compressed, so main context shrinks per delegation.
15
14
16
15
## When to use cavecrew vs alternatives
17
16
···
25
24
| Deep code review with rationale + alternatives | `Code Reviewer` (vanilla) |
26
25
| One-line answer you already know | Main thread, no subagent |
27
26
28
-
Rule of thumb: **if you'd want the subagent's output in 1/3 the tokens, pick cavecrew. If you'd want prose, pick vanilla.**
27
+
Rule of thumb: **if you'd want subagent's output in 1/3 tokens, pick cavecrew. If you'd want prose, pick vanilla.**
29
28
30
29
## Why this exists (the real win)
31
30
32
-
Subagent tool results get injected into main context verbatim. A vanilla `Explore` that returns 2k tokens of prose costs 2k tokens of main-context budget every time. The same finding from `cavecrew-investigator` returns ~700 tokens. Across 20 delegations in one session that's the difference between context exhaustion and finishing the task.
31
+
Subagent tool results get injected into main context verbatim. vanilla `Explore` that returns 2k tokens of prose costs 2k tokens of main-context budget every time. same finding from `cavecrew-investigator` returns ~700 tokens. Across 20 delegations in one session that's difference between context exhaustion and finishing task.
33
32
34
33
## Output contracts
35
34
···
62
61
**Locate → fix → verify** (most common):
63
62
1. `cavecrew-investigator` returns site list.
64
63
2. Main thread picks 1-2 sites, hands paths to `cavecrew-builder`.
65
-
3. `cavecrew-reviewer` audits the diff.
64
+
3. `cavecrew-reviewer` audits diff.
66
65
67
66
**Parallel scout** (when investigation is broad):
68
67
Spawn 2-3 `cavecrew-investigator` calls in one message (different angles: defs vs callers vs tests). Aggregate in main thread.
···
72
71
73
72
## What NOT to do
74
73
75
-
- Don't use `cavecrew-builder` when you don't already know the file. Spawn investigator first or main thread will eat tokens passing context.
76
-
- Don't chain `cavecrew-investigator → cavecrew-builder` for a 5-file refactor. Builder will return `too-big.` and you'll have wasted a turn.
74
+
- Don't use `cavecrew-builder` when you don't already know file. Spawn investigator first or main thread will eat tokens passing context.
75
+
- Don't chain `cavecrew-investigator → cavecrew-builder` for 5-file refactor. Builder will return `too-big.` and you'll have wasted turn.
77
76
- Don't ask `cavecrew-reviewer` for "general feedback" — it returns findings only, no architecture opinions. Use `Code Reviewer` for that.
78
-
- Don't expect prose. Cavecrew output is structured, sometimes terse to the point of cryptic. If a human will read it directly, paraphrase.
77
+
- Don't expect prose. Cavecrew output is structured, sometimes terse to point of cryptic. If human will read it directly, paraphrase.
79
78
80
79
## Auto-clarity (inherited)
81
80
+11
-11
skills/caveman-commit/SKILL.md
+11
-11
skills/caveman-commit/SKILL.md
···
1
1
---
2
2
name: caveman-commit
3
3
description: >
4
-
Ultra-compressed commit message generator. Cuts noise from commit messages while preserving
5
-
intent and reasoning. Conventional Commits format. Subject ≤50 chars, body only when "why"
6
-
isn't obvious. Use when user says "write a commit", "commit message", "generate commit",
7
-
"/commit", or invokes /caveman-commit. Auto-triggers when staging changes.
4
+
Ultra-compressed commit message generator. Cuts noise from commit messages while preserving
5
+
intent and reasoning. Conventional Commits format. Subject ≤50 chars, body only when "why"
6
+
isn't obvious. Use when user says "write commit", "commit message", "generate commit",
7
+
"/commit", or invokes /caveman-commit. Auto-triggers when staging changes.
8
8
---
9
9
10
10
Write commit messages terse and exact. Conventional Commits format. No fluff. Why over what.
···
17
17
- Imperative mood: "add", "fix", "remove" — not "added", "adds", "adding"
18
18
- ≤50 chars when possible, hard cap 72
19
19
- No trailing period
20
-
- Match project convention for capitalization after the colon
20
+
- Match project convention for capitalization after colon
21
21
22
22
**Body (only if needed):**
23
23
- Skip entirely when subject is self-explanatory
···
27
27
- Reference issues/PRs at end: `Closes #42`, `Refs #17`
28
28
29
29
**What NEVER goes in:**
30
-
- "This commit does X", "I", "we", "now", "currently" — the diff says what
30
+
- "This commit does X", "I", "we", "now", "currently" — diff says what
31
31
- "As requested by..." — use Co-authored-by trailer
32
32
- "Generated with Claude Code" or any AI attribution
33
33
- Emoji (unless project convention requires)
34
-
- Restating the file name when scope already says it
34
+
- Restating file name when scope already says it
35
35
36
36
## Examples
37
37
38
-
Diff: new endpoint for user profile with body explaining the why
39
-
- ❌ "feat: add a new endpoint to get user profile information from the database"
38
+
Diff: new endpoint for user profile with body explaining why
39
+
- ❌ "feat: add new endpoint to get user profile information from database"
40
40
- ✅
41
41
```
42
42
feat(api): add GET /users/:id/profile
···
58
58
59
59
## Auto-Clarity
60
60
61
-
Always include body for: breaking changes, security fixes, data migrations, anything reverting a prior commit. Never compress these into subject-only — future debuggers need the context.
61
+
Always include body for: breaking changes, security fixes, data migrations, anything reverting prior commit. Never compress these into subject-only — future debuggers need context.
62
62
63
63
## Boundaries
64
64
65
-
Only generates the commit message. Does not run `git commit`, does not stage files, does not amend. Output the message as a code block ready to paste. "stop caveman-commit" or "normal mode": revert to verbose commit style.
65
+
Only generates commit message. Does not run `git commit`, does not stage files, does not amend. Output message as code block ready to paste. "stop caveman-commit" or "normal mode": revert to verbose commit style.
+10
-10
skills/caveman-compress/README.md
+10
-10
skills/caveman-compress/README.md
···
1
1
<p align="center">
2
-
<img src="https://em-content.zobj.net/source/apple/391/rock_1faa8.png" width="80" />
2
+
<img src="https://em-content.zobj.net/source/apple/391/rock_1faa8.png" width="80" />
3
3
</p>
4
4
5
5
<h1 align="center">caveman-compress</h1>
6
6
7
7
<p align="center">
8
-
<strong>shrink memory file. save token every session.</strong>
8
+
<strong>shrink memory file. save token every session.</strong>
9
9
</p>
10
10
11
11
---
12
12
13
-
A Claude Code skill that compresses your project memory files (`CLAUDE.md`, todos, preferences) into caveman format — so every session loads fewer tokens automatically.
13
+
Claude Code skill that compresses your project memory files (`CLAUDE.md`, todos, preferences) into caveman format — so every session loads fewer tokens automatically.
14
14
15
15
Claude read `CLAUDE.md` on every session start. If file big, cost big. Caveman make file small. Cost go down forever.
16
16
···
25
25
CLAUDE.original.md ← human-readable backup (you edit this)
26
26
```
27
27
28
-
Original never lost. You can read and edit `.original.md`. Run skill again to re-compress after edits.
28
+
Original never lost. read and edit `.original.md`. Run skill again to re-compress after edits.
29
29
30
30
## Benchmarks
31
31
···
50
50
51
51
### 📄 Original (706 tokens)
52
52
53
-
> "I strongly prefer TypeScript with strict mode enabled for all new code. Please don't use `any` type unless there's genuinely no way around it, and if you do, leave a comment explaining the reasoning. I find that taking the time to properly type things catches a lot of bugs before they ever make it to runtime."
53
+
> "I strongly prefer TypeScript with strict mode enabled for all new code. Please don't use `any` type unless there's genuinely no way around it, and if you do, leave comment explaining reasoning. I find that taking time to properly type things catches lot of bugs before they ever make it to runtime."
54
54
55
55
</td>
56
56
<td width="50%">
···
67
67
68
68
## Security
69
69
70
-
`caveman-compress` is flagged as Snyk High Risk due to subprocess and file I/O patterns detected by static analysis. This is a false positive — see [SECURITY.md](./SECURITY.md) for a full explanation of what the skill does and does not do.
70
+
`caveman-compress` is flagged as Snyk High Risk due to subprocess and file I/O patterns detected by static analysis. This is false positive — see [SECURITY.md](./SECURITY.md) for full explanation of what skill does and does not do.
71
71
72
72
## Install
73
73
74
-
Compress is built in with the `caveman` plugin. Install `caveman` once, then use `/caveman:compress`.
74
+
Compress is built in with `caveman` plugin. Install `caveman` once, then use `/caveman:compress`.
75
75
76
-
If you need local files, the compress skill lives at:
76
+
If you need local files, compress skill lives at:
77
77
78
78
```bash
79
79
caveman-compress/
···
142
142
143
143
## Why This Matter
144
144
145
-
`CLAUDE.md` loads on **every session start**. A 1000-token project memory file costs tokens every single time you open a project. Over 100 sessions that's 100,000 tokens of overhead — just for context you already wrote.
145
+
`CLAUDE.md` loads on **every session start**. 1000-token project memory file costs tokens every single time you open project. Over 100 sessions that's 100,000 tokens of overhead — for context you already wrote.
146
146
147
147
Caveman cut that by ~46% on average. Same instructions. Same accuracy. Less waste.
148
148
···
157
157
158
158
## Part of Caveman
159
159
160
-
This skill is part of the [caveman](https://github.com/JuliusBrussee/caveman) toolkit — making Claude use fewer tokens without losing accuracy.
160
+
This skill is part of [caveman](https://github.com/JuliusBrussee/caveman) toolkit — making Claude use fewer tokens without losing accuracy.
161
161
162
162
- **caveman** — make Claude *speak* like caveman (cuts response tokens ~65%)
163
163
- **caveman-compress** — make Claude *read* less (cuts context tokens ~46%)
+7
-7
skills/caveman-compress/SECURITY.md
+7
-7
skills/caveman-compress/SECURITY.md
···
2
2
3
3
## Snyk High Risk Rating
4
4
5
-
`caveman-compress` receives a Snyk High Risk rating due to static analysis heuristics. This document explains what the skill does and does not do.
5
+
`caveman-compress` receives Snyk High Risk rating due to static analysis heuristics. This document explains what skill does and does not do.
6
6
7
7
### What triggers the rating
8
8
9
-
1. **subprocess usage**: The skill calls the `claude` CLI via `subprocess.run()` as a fallback when `ANTHROPIC_API_KEY` is not set. The subprocess call uses a fixed argument list — no shell interpolation occurs. User file content is passed via stdin, not as a shell argument.
9
+
1. **subprocess usage**: skill calls `claude` CLI via `subprocess.run()` as fallback when `ANTHROPIC_API_KEY` is not set. subprocess call uses fixed argument list — no shell interpolation occurs. User file content is passed via stdin, not as shell argument.
10
10
11
-
2. **File read/write**: The skill reads the file the user explicitly points it at, compresses it, and writes the result back to the same path. A `.original.md` backup is saved alongside it. No files outside the user-specified path are read or written.
11
+
2. **File read/write**: skill reads file user explicitly points it at, compresses it, and writes result back to same path. `.original.md` backup is saved alongside it. No files outside user-specified path are read or written.
12
12
13
13
### What the skill does NOT do
14
14
15
15
- Does not execute user file content as code
16
16
- Does not make network requests except to Anthropic's API (via SDK or CLI)
17
-
- Does not access files outside the path the user provides
17
+
- Does not access files outside path user provides
18
18
- Does not use shell=True or string interpolation in subprocess calls
19
-
- Does not collect or transmit any data beyond the file being compressed
19
+
- Does not collect or transmit any data beyond file being compressed
20
20
21
21
### Auth behavior
22
22
23
-
If `ANTHROPIC_API_KEY` is set, the skill uses the Anthropic Python SDK directly (no subprocess). If not set, it falls back to the `claude` CLI, which uses the user's existing Claude desktop authentication.
23
+
If `ANTHROPIC_API_KEY` is set, skill uses Anthropic Python SDK directly (no subprocess). If not set, it falls back to `claude` CLI, which uses user's existing Claude desktop authentication.
24
24
25
25
### File size limit
26
26
···
28
28
29
29
### Reporting a vulnerability
30
30
31
-
If you believe you've found a genuine security issue, please open a GitHub issue with the label `security`.
31
+
If you believe you've found genuine security issue, please open GitHub issue with label `security`.
+16
-16
skills/caveman-compress/SKILL.md
+16
-16
skills/caveman-compress/SKILL.md
···
1
1
---
2
2
name: caveman-compress
3
3
description: >
4
-
Compress natural language memory files (CLAUDE.md, todos, preferences) into caveman format
5
-
to save input tokens. Preserves all technical substance, code, URLs, and structure.
6
-
Compressed version overwrites the original file. Human-readable backup saved as FILE.original.md.
7
-
Trigger: /caveman:compress FILEPATH or "compress memory file"
4
+
Compress natural language memory files (CLAUDE.md, todos, preferences) into caveman format
5
+
to save input tokens. Preserves all technical substance, code, URLs, and structure.
6
+
Compressed version overwrites original file. Human-readable backup saved as FILE.original.md.
7
+
Trigger: /caveman:compress FILEPATH or "compress memory file"
8
8
---
9
9
10
10
# Caveman Compress
···
15
15
16
16
## Trigger
17
17
18
-
`/caveman:compress <filepath>` or when user asks to compress a memory file.
18
+
`/caveman:compress <filepath>` or when user asks to compress memory file.
19
19
20
20
## Process
21
21
22
-
1. The compression scripts live in `caveman-compress/scripts/` (adjacent to this SKILL.md). If the path is not immediately available, search for `caveman-compress/scripts/__main__.py`.
22
+
1. compression scripts live in `caveman-compress/scripts/` (adjacent to this SKILL.md). If path is not immediately available, search for `caveman-compress/scripts/__main__.py`.
23
23
24
24
2. Run:
25
25
26
26
cd caveman-compress && python3 -m scripts <absolute_filepath>
27
27
28
-
3. The CLI will:
28
+
3. CLI will:
29
29
- detect file type (no tokens)
30
30
- call Claude to compress
31
31
- validate output (no tokens)
···
43
43
- Pleasantries: "sure", "certainly", "of course", "happy to", "I'd recommend"
44
44
- Hedging: "it might be worth", "you could consider", "it would be good to"
45
45
- Redundant phrasing: "in order to" → "to", "make sure to" → "ensure", "the reason is because" → "because"
46
-
- Connective fluff: "however", "furthermore", "additionally", "in addition"
46
+
- Connective fluff: however, furthermore, additionally, in addition
47
47
48
48
### Preserve EXACTLY (never modify)
49
49
- Code blocks (fenced ``` and indented)
···
66
66
### Compress
67
67
- Use short synonyms: "big" not "extensive", "fix" not "implement a solution for", "use" not "utilize"
68
68
- Fragments OK: "Run tests before commit" not "You should always run tests before committing"
69
-
- Drop "you should", "make sure to", "remember to" — just state the action
70
-
- Merge redundant bullets that say the same thing differently
71
-
- Keep one example where multiple examples show the same pattern
69
+
- Drop "you should", "make sure to", "remember to"; state action
70
+
- Merge redundant bullets that say same thing differently
71
+
- Keep one example where multiple examples show same pattern
72
72
73
73
CRITICAL RULE:
74
74
Anything inside ``` ... ``` must be copied EXACTLY.
···
90
90
## Pattern
91
91
92
92
Original:
93
-
> You should always make sure to run the test suite before pushing any changes to the main branch. This is important because it helps catch bugs early and prevents broken builds from being deployed to production.
93
+
> always ensure run test suite before pushing any changes to main branch. This is important because it helps catch bugs early and prevents broken builds from being deployed to production.
94
94
95
95
Compressed:
96
96
> Run tests before push to main. Catch bugs early, prevent broken prod deploys.
97
97
98
98
Original:
99
-
> The application uses a microservices architecture with the following components. The API gateway handles all incoming requests and routes them to the appropriate service. The authentication service is responsible for managing user sessions and JWT tokens.
99
+
> application uses microservices architecture with following components. API gateway handles all incoming requests and routes them to appropriate service. authentication service is responsible for managing user sessions and JWT tokens.
100
100
101
101
Compressed:
102
102
> Microservices architecture. API gateway route all requests to services. Auth service manage user sessions + JWT tokens.
103
103
104
104
## Boundaries
105
105
106
-
- ONLY compress natural language files (.md, .txt, .typ, .typst, .tex, extensionless)
107
-
- NEVER modify: .py, .js, .ts, .json, .yaml, .yml, .toml, .env, .lock, .css, .html, .xml, .sql, .sh
108
-
- If file has mixed content (prose + code), compress ONLY the prose sections
106
+
- ONLY compress natural language files (.md,.txt,.typ,.typst,.tex, extensionless)
107
+
- NEVER modify:.py,.js,.ts,.json,.yaml,.yml,.toml,.env,.lock,.css,.html,.xml,.sql,.sh
108
+
- If file has mixed content (prose + code), compress ONLY prose sections
109
109
- If unsure whether something is code or prose, leave it unchanged
110
110
- Original file is backed up as FILE.original.md before overwriting
111
111
- Never compress FILE.original.md (skip it)
+3
-3
skills/caveman-help/SKILL.md
+3
-3
skills/caveman-help/SKILL.md
···
1
1
---
2
2
name: caveman-help
3
3
description: >
4
-
Quick-reference card for all caveman modes, skills, and commands.
5
-
One-shot display, not a persistent mode. Trigger: /caveman-help,
6
-
"caveman help", "what caveman commands", "how do I use caveman".
4
+
Quick-reference card for all caveman modes, skills, and commands.
5
+
One-shot display, not persistent mode. Trigger: /caveman-help,
6
+
"caveman help", "what caveman commands", "how do I use caveman".
7
7
---
8
8
9
9
# Caveman Help
+15
-15
skills/caveman-review/SKILL.md
+15
-15
skills/caveman-review/SKILL.md
···
1
1
---
2
2
name: caveman-review
3
3
description: >
4
-
Ultra-compressed code review comments. Cuts noise from PR feedback while preserving
5
-
the actionable signal. Each comment is one line: location, problem, fix. Use when user
6
-
says "review this PR", "code review", "review the diff", "/review", or invokes
7
-
/caveman-review. Auto-triggers when reviewing pull requests.
4
+
Ultra-compressed code review comments. Cuts noise from PR feedback while preserving
5
+
actionable signal. Each comment is one line: location, problem, fix. Use when user
6
+
says "review this PR", "code review", "review diff", "/review", or invokes
7
+
/caveman-review. Auto-triggers when reviewing pull requests.
8
8
---
9
9
10
10
Write code review comments terse and actionable. One line per finding. Location, problem, fix. No throat-clearing.
···
17
17
- `🔴 bug:` — broken behavior, will cause incident
18
18
- `🟡 risk:` — works but fragile (race, missing null check, swallowed error)
19
19
- `🔵 nit:` — style, naming, micro-optim. Author can ignore
20
-
- `❓ q:` — genuine question, not a suggestion
20
+
- `❓ q:` — genuine question, not suggestion
21
21
22
22
**Drop:**
23
-
- "I noticed that...", "It seems like...", "You might want to consider..."
24
-
- "This is just a suggestion but..." — use `nit:` instead
25
-
- "Great work!", "Looks good overall but..." — say it once at the top, not per comment
26
-
- Restating what the line does — the reviewer can read the diff
23
+
- "I noticed that...", "It seems like...", " want to consider..."
24
+
- "This is suggestion but..." — use `nit:` instead
25
+
- "Great work!", "Looks good overall but..." — say it once at top, not per comment
26
+
- Restating what line does — reviewer can read diff
27
27
- Hedging ("perhaps", "maybe", "I think") — if unsure use `q:`
28
28
29
29
**Keep:**
30
30
- Exact line numbers
31
31
- Exact symbol/function/variable names in backticks
32
32
- Concrete fix, not "consider refactoring this"
33
-
- The *why* if the fix isn't obvious from the problem statement
33
+
- *why* if fix isn't obvious from problem statement
34
34
35
35
## Examples
36
36
37
-
❌ "I noticed that on line 42 you're not checking if the user object is null before accessing the email property. This could potentially cause a crash if the user is not found in the database. You might want to add a null check here."
37
+
❌ "I noticed that on line 42 you're not checking if user object is null before accessing email property. This could potentially cause crash if user is not found in database. want to add null check here."
38
38
39
39
✅ `L42: 🔴 bug: user can be null after .find(). Add guard before .email.`
40
40
41
-
❌ "It looks like this function is doing a lot of things and might benefit from being broken up into smaller functions for readability."
41
+
❌ "It looks like this function is doing lot of things and might benefit from being broken up into smaller functions for readability."
42
42
43
43
✅ `L88-140: 🔵 nit: 50-line fn does 4 things. Extract validate/normalize/persist.`
44
44
45
-
❌ "Have you considered what happens if the API returns a 429? I think we should probably handle that case."
45
+
❌ "Have you considered what happens if API returns 429? I think we should probably handle that case."
46
46
47
47
✅ `L23: 🟡 risk: no retry on 429. Wrap in withBackoff(3).`
48
48
49
49
## Auto-Clarity
50
50
51
-
Drop terse mode for: security findings (CVE-class bugs need full explanation + reference), architectural disagreements (need rationale, not just a one-liner), and onboarding contexts where the author is new and needs the "why". In those cases write a normal paragraph, then resume terse for the rest.
51
+
Drop terse mode for: security findings (CVE-class bugs need full explanation + reference), architectural disagreements (need rationale, not one-liner), and onboarding contexts where author is new and needs "why". In those cases write normal paragraph, then resume terse for rest.
52
52
53
53
## Boundaries
54
54
55
-
Reviews only — does not write the code fix, does not approve/request-changes, does not run linters. Output the comment(s) ready to paste into the PR. "stop caveman-review" or "normal mode": revert to verbose review style.
55
+
Reviews only — does not write code fix, does not approve/request-changes, does not run linters. Output comment(s) ready to paste into PR. "stop caveman-review" or "normal mode": revert to verbose review style.
+5
-5
skills/caveman-stats/SKILL.md
+5
-5
skills/caveman-stats/SKILL.md
···
1
1
---
2
2
name: caveman-stats
3
3
description: >
4
-
Show real token usage and estimated savings for the current session.
5
-
Reads directly from the Claude Code session log — no AI estimation.
6
-
Triggers on /caveman-stats. Output is injected by the mode-tracker hook;
7
-
the model itself does not compute the numbers.
4
+
Show real token usage and estimated savings for current session.
5
+
Reads directly from Claude Code session log — no AI estimation.
6
+
Triggers on /caveman-stats. Output is injected by mode-tracker hook;
7
+
model itself does not compute numbers.
8
8
---
9
9
10
-
This skill is delivered by `hooks/caveman-stats.js` (read by `hooks/caveman-mode-tracker.js` on `/caveman-stats`). The model does not need to do anything when this skill fires — the hook returns `decision: "block"` with the formatted stats as the reason. The user sees the numbers immediately.
10
+
This skill is delivered by `hooks/caveman-stats.js` (read by `hooks/caveman-mode-tracker.js` on `/caveman-stats`). model does not need to do anything when this skill fires — hook returns `decision: "block"` with formatted stats as reason. user sees numbers immediately.
+10
-10
skills/caveman/SKILL.md
+10
-10
skills/caveman/SKILL.md
···
1
1
---
2
2
name: caveman
3
3
description: >
4
-
Ultra-compressed communication mode. Cuts token usage ~75% by speaking like caveman
5
-
while keeping full technical accuracy. Supports intensity levels: lite, full (default), ultra,
6
-
wenyan-lite, wenyan-full, wenyan-ultra.
7
-
Use when user says "caveman mode", "talk like caveman", "use caveman", "less tokens",
8
-
"be brief", or invokes /caveman. Also auto-triggers when token efficiency is requested.
4
+
Ultra-compressed communication mode. Cuts token usage ~75% by speaking like caveman
5
+
while keeping full technical accuracy. Supports intensity levels: lite, full (default), ultra,
6
+
wenyan-lite, wenyan-full, wenyan-ultra.
7
+
Use when user says "caveman mode", "talk like caveman", "use caveman", "less tokens",
8
+
"be brief", or invokes /caveman. Also auto-triggers when token efficiency is requested.
9
9
---
10
10
11
11
Respond terse like smart caveman. All technical substance stay. Only fluff die.
···
18
18
19
19
## Rules
20
20
21
-
Drop: articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course/happy to), hedging. Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). Technical terms exact. Code blocks unchanged. Errors quoted exact.
21
+
Drop: articles (//), filler (////), pleasantries (sure/certainly/of course/happy to), hedging. Fragments OK. Short synonyms (big not extensive, fix not "implement solution for"). Technical terms exact. Code blocks unchanged. Errors quoted exact.
22
22
23
23
Pattern: `[thing] [action] [reason]. [next step].`
24
24
25
-
Not: "Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by..."
25
+
Not: "Sure! I'd be happy to help you with that. issue you're experiencing is likely caused by..."
26
26
Yes: "Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:"
27
27
28
28
## Intensity
···
37
37
| **wenyan-ultra** | Extreme abbreviation while keeping classical Chinese feel. Maximum compression, ultra terse |
38
38
39
39
Example — "Why React component re-render?"
40
-
- lite: "Your component re-renders because you create a new object reference each render. Wrap it in `useMemo`."
40
+
- lite: "Your component re-renders because you create new object reference each render. Wrap it in `useMemo`."
41
41
- full: "New object ref each render. Inline object prop = new ref = re-render. Wrap in `useMemo`."
42
42
- ultra: "Inline obj prop → new ref → re-render. `useMemo`."
43
43
- wenyan-lite: "組件頻重繪，以每繪新生對象參照故。以 useMemo 包之。"
44
-
- wenyan-full: "物出新參照，致重繪。useMemo .Wrap之。"
44
+
- wenyan-full: "物出新參照，致重繪。useMemo.Wrap之。"
45
45
- wenyan-ultra: "新參照→重繪。useMemo Wrap。"
46
46
47
47
Example — "Explain database connection pooling."
···
63
63
Resume caveman after clear part done.
64
64
65
65
Example — destructive op:
66
-
> **Warning:** This will permanently delete all rows in the `users` table and cannot be undone.
66
+
> **Warning:** This will permanently delete all rows in `users` table and cannot be undone.
67
67
> ```sql
68
68
> DROP TABLE users;
69
69
> ```
+12
-12
skills/clarify/SKILL.md
+12
-12
skills/clarify/SKILL.md
···
1
1
---
2
2
name: clarify
3
-
description: "Improve unclear UX copy, error messages, microcopy, labels, and instructions to make interfaces easier to understand. Use when the user mentions confusing text, unclear labels, bad error messages, hard-to-follow instructions, or wanting better UX writing."
3
+
description: "Improve unclear UX copy, error messages, microcopy, labels, and instructions to make interfaces easier to understand. Use when user mentions confusing text, unclear labels, bad error messages, hard-to-follow instructions, or wanting better UX writing."
4
4
argument-hint: "[target]"
5
5
user-invocable: true
6
6
---
7
7
8
-
Identify and improve unclear, confusing, or poorly written interface text to make the product easier to understand and use.
8
+
Identify and improve unclear, confusing, or poorly written interface text to make product easier to understand and use.
9
9
10
10
## MANDATORY PREPARATION
11
11
12
-
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. gather: audience technical level and users mental state in context.
12
+
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and Context Gathering Protocol. Follow protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. gather: audience technical level and users mental state in context.
13
13
14
14
---
15
15
16
16
## Assess Current Copy
17
17
18
-
Identify what makes the text unclear or ineffective.
18
+
Identify what makes text unclear or ineffective.
19
19
20
20
### 1. Find clarity problems
21
21
- **Jargon**: Technical terms users will not understand
···
36
36
37
37
## Plan Copy Improvements
38
38
39
-
Create a strategy for clearer communication.
39
+
Create strategy for clearer communication.
40
40
41
41
- **Primary message**: What is ONE thing users need to know?
42
42
- **Action needed**: What should users do next (if anything)?
43
43
- **Tone**: How should this feel? (Helpful? Apologetic? Encouraging?)
44
44
- **Constraints**: Length limits, brand voice, localization considerations
45
45
46
-
**IMPORTANT**: Good UX writing is invisible. Users should understand immediately without noticing the words.
46
+
**IMPORTANT**: Good UX writing is invisible. Users should understand immediately without noticing words.
47
47
48
48
## Improve Copy Systematically
49
49
···
54
54
**Good**: "You do not have permission to view this page. Contact your admin for access."
55
55
56
56
**Bad**: "Invalid input"
57
-
**Good**: "Email addresses need an @ symbol. Try: name@example.com"
57
+
**Good**: "Email addresses need @ symbol. Try: name@example.com"
58
58
59
59
**Principles**:
60
60
- Explain what went wrong in plain language
···
88
88
- Be specific ("Save" is better than "OK")
89
89
90
90
### Help Text and Tooltips
91
-
**Bad**: "This is the username field"
92
-
**Good**: "Choose a username. You can change this later in Settings."
91
+
**Bad**: "This is username field"
92
+
**Good**: "Choose username. change this later in Settings."
93
93
94
94
**Principles**:
95
95
- Add value (do not repeat label)
···
102
102
**Good**: "No projects yet. Create your first project to get started."
103
103
104
104
**Principles**:
105
-
- Explain why it is empty (if not obvious)
105
+
- Explain why it's empty (if not obvious)
106
106
- Show next action clearly
107
107
- Make it welcoming, not dead-end
108
108
···
122
122
123
123
**Principles**:
124
124
- Set expectations (how long?)
125
-
- Explain what is happening (when it is not obvious)
125
+
- Explain what is happening (when it's not obvious)
126
126
- Show progress when possible
127
127
- Offer escape hatch if appropriate ("Cancel")
128
128
···
179
179
- **Consistency**: Does it match terminology elsewhere?
180
180
- **Tone**: Is it appropriate for situation?
181
181
182
-
Remember: You are a clarity expert with excellent communication skills. Write like you are explaining to a smart friend who is unfamiliar with the product. Be clear, be helpful, be human.
182
+
Remember: You are clarity expert with excellent communication skills. Write like you are explaining to smart friend who is unfamiliar with product. Be clear, be helpful, be human.
-182
skills/clarify/SKILL.md.original.md
-182
skills/clarify/SKILL.md.original.md
···
1
-
---
2
-
name: clarify
3
-
description: "Improve unclear UX copy, error messages, microcopy, labels, and instructions to make interfaces easier to understand. Use when the user mentions confusing text, unclear labels, bad error messages, hard-to-follow instructions, or wanting better UX writing."
4
-
argument-hint: "[target]"
5
-
user-invocable: true
6
-
---
7
-
8
-
Identify and improve unclear, confusing, or poorly written interface text to make the product easier to understand and use.
9
-
10
-
## MANDATORY PREPARATION
11
-
12
-
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. Additionally gather: audience technical level and users mental state in context.
13
-
14
-
---
15
-
16
-
## Assess Current Copy
17
-
18
-
Identify what makes the text unclear or ineffective.
19
-
20
-
### 1. Find clarity problems
21
-
- **Jargon**: Technical terms users will not understand
22
-
- **Ambiguity**: Multiple interpretations possible
23
-
- **Passive voice**: "Your file has been uploaded" vs "We uploaded your file"
24
-
- **Length**: Too wordy or too terse
25
-
- **Assumptions**: Assuming user knowledge they do not have
26
-
- **Missing context**: Users do not know what to do or why
27
-
- **Tone mismatch**: Too formal, too casual, or inappropriate for situation
28
-
29
-
### 2. Understand the context
30
-
- Who is the audience? (Technical? General? First-time users?)
31
-
- What is the user mental state? (Stressed during error? Confident during success?)
32
-
- What is the action? (What do we want users to do?)
33
-
- What is the constraint? (Character limits? Space limitations?)
34
-
35
-
**CRITICAL**: Clear copy helps users succeed. Unclear copy creates frustration, errors, and support tickets.
36
-
37
-
## Plan Copy Improvements
38
-
39
-
Create a strategy for clearer communication.
40
-
41
-
- **Primary message**: What is the ONE thing users need to know?
42
-
- **Action needed**: What should users do next (if anything)?
43
-
- **Tone**: How should this feel? (Helpful? Apologetic? Encouraging?)
44
-
- **Constraints**: Length limits, brand voice, localization considerations
45
-
46
-
**IMPORTANT**: Good UX writing is invisible. Users should understand immediately without noticing the words.
47
-
48
-
## Improve Copy Systematically
49
-
50
-
Refine text across these common areas.
51
-
52
-
### Error Messages
53
-
**Bad**: "Error 403: Forbidden"
54
-
**Good**: "You do not have permission to view this page. Contact your admin for access."
55
-
56
-
**Bad**: "Invalid input"
57
-
**Good**: "Email addresses need an @ symbol. Try: name@example.com"
58
-
59
-
**Principles**:
60
-
- Explain what went wrong in plain language
61
-
- Suggest how to fix it
62
-
- Do not blame the user
63
-
- Include examples when helpful
64
-
- Link to help or support if applicable
65
-
66
-
### Form Labels and Instructions
67
-
**Bad**: "DOB (MM/DD/YYYY)"
68
-
**Good**: "Date of birth" (with placeholder showing format)
69
-
70
-
**Bad**: "Enter value here"
71
-
**Good**: "Your email address" or "Company name"
72
-
73
-
**Principles**:
74
-
- Use clear, specific labels (not generic placeholders)
75
-
- Show format expectations with examples
76
-
- Explain why you are asking (when not obvious)
77
-
- Put instructions before the field, not after
78
-
- Keep required field indicators clear
79
-
80
-
### Button and CTA Text
81
-
**Bad**: "Click here" | "Submit" | "OK"
82
-
**Good**: "Create account" | "Save changes" | "Got it, thanks"
83
-
84
-
**Principles**:
85
-
- Describe the action specifically
86
-
- Use active voice (verb plus noun)
87
-
- Match user mental model
88
-
- Be specific ("Save" is better than "OK")
89
-
90
-
### Help Text and Tooltips
91
-
**Bad**: "This is the username field"
92
-
**Good**: "Choose a username. You can change this later in Settings."
93
-
94
-
**Principles**:
95
-
- Add value (do not just repeat the label)
96
-
- Answer the implicit question ("What is this?" or "Why do you need this?")
97
-
- Keep it brief but complete
98
-
- Link to detailed docs if needed
99
-
100
-
### Empty States
101
-
**Bad**: "No items"
102
-
**Good**: "No projects yet. Create your first project to get started."
103
-
104
-
**Principles**:
105
-
- Explain why it is empty (if not obvious)
106
-
- Show next action clearly
107
-
- Make it welcoming, not dead-end
108
-
109
-
### Success Messages
110
-
**Bad**: "Success"
111
-
**Good**: "Settings saved! Your changes will take effect immediately."
112
-
113
-
**Principles**:
114
-
- Confirm what happened
115
-
- Explain what happens next (if relevant)
116
-
- Be brief but complete
117
-
- Match user emotional moment (celebrate big wins)
118
-
119
-
### Loading States
120
-
**Bad**: "Loading..." (for 30+ seconds)
121
-
**Good**: "Analyzing your data... this usually takes 30-60 seconds"
122
-
123
-
**Principles**:
124
-
- Set expectations (how long?)
125
-
- Explain what is happening (when it is not obvious)
126
-
- Show progress when possible
127
-
- Offer escape hatch if appropriate ("Cancel")
128
-
129
-
### Confirmation Dialogs
130
-
**Bad**: "Are you sure?"
131
-
**Good**: "Delete 'Project Alpha'? This cannot be undone."
132
-
133
-
**Principles**:
134
-
- State the specific action
135
-
- Explain consequences (especially for destructive actions)
136
-
- Use clear button labels ("Delete project" not "Yes")
137
-
- Do not overuse confirmations (only for risky actions)
138
-
139
-
### Navigation and Wayfinding
140
-
**Bad**: Generic labels like "Items" | "Things" | "Stuff"
141
-
**Good**: Specific labels like "Your projects" | "Team members" | "Settings"
142
-
143
-
**Principles**:
144
-
- Be specific and descriptive
145
-
- Use language users understand (not internal jargon)
146
-
- Make hierarchy clear
147
-
- Consider information scent (breadcrumbs, current location)
148
-
149
-
## Apply Clarity Principles
150
-
151
-
Every piece of copy should follow these rules:
152
-
153
-
1. **Be specific**: "Enter email" not "Enter value"
154
-
2. **Be concise**: Cut unnecessary words (but do not sacrifice clarity)
155
-
3. **Be active**: "Save changes" not "Changes will be saved"
156
-
4. **Be human**: "Oops, something went wrong" not "System error encountered"
157
-
5. **Be helpful**: Tell users what to do, not just what happened
158
-
6. **Be consistent**: Use same terms throughout (do not vary for variety)
159
-
160
-
**NEVER**:
161
-
- Use jargon without explanation
162
-
- Blame users ("You made an error" becomes "This field is required")
163
-
- Be vague ("Something went wrong" without explanation)
164
-
- Use passive voice unnecessarily
165
-
- Write overly long explanations (be concise)
166
-
- Use humor for errors (be empathetic instead)
167
-
- Assume technical knowledge
168
-
- Vary terminology (pick one term and stick with it)
169
-
- Repeat information (headers restating intros, redundant explanations)
170
-
- Use placeholders as the only labels (they disappear when users type)
171
-
172
-
## Verify Improvements
173
-
174
-
Test that copy improvements work.
175
-
176
-
- **Comprehension**: Can users understand without context?
177
-
- **Actionability**: Do users know what to do next?
178
-
- **Brevity**: Is it as short as possible while remaining clear?
179
-
- **Consistency**: Does it match terminology elsewhere?
180
-
- **Tone**: Is it appropriate for the situation?
181
-
182
-
Remember: You are a clarity expert with excellent communication skills. Write like you are explaining to a smart friend who is unfamiliar with the product. Be clear, be helpful, be human.
+8
-8
skills/colorize/SKILL.md
+8
-8
skills/colorize/SKILL.md
···
1
1
---
2
2
name: colorize
3
-
description: "Add strategic color to features that are too monochromatic or lack visual interest, making interfaces more engaging and expressive. Use when the user mentions the design looking gray, dull, lacking warmth, needing more color, or wanting a more vibrant or expressive palette."
3
+
description: "Add strategic color to features that are too monochromatic or lack visual interest, making interfaces more engaging and expressive. Use when user mentions design looking gray, dull, lacking warmth, needing more color, or wanting more vibrant or expressive palette."
4
4
argument-hint: "[target]"
5
5
user-invocable: true
6
6
---
···
9
9
10
10
## MANDATORY PREPARATION
11
11
12
-
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. gather: existing brand colors.
12
+
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and Context Gathering Protocol. Follow protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. gather: existing brand colors.
13
13
14
14
---
15
15
16
16
## Assess Color Opportunity
17
17
18
-
Analyze the current state and identify opportunities.
18
+
Analyze current state and identify opportunities.
19
19
20
20
### 1. Understand current state
21
21
- **Color absence**: Pure grayscale? Limited neutrals? One timid accent?
···
31
31
- **Wayfinding**: Helping users navigate and understand structure
32
32
- **Delight**: Moments of visual interest and personality
33
33
34
-
If any of these are unclear from the codebase, {{ask_instruction}}
34
+
If any of these are unclear from codebase, {{ask_instruction}}
35
35
36
-
**CRITICAL**: More color does not equal better. Strategic color beats rainbow vomit every time. Every color should have a purpose.
36
+
**CRITICAL**: More color does not equal better. Strategic color beats rainbow vomit every time. Every color should have purpose.
37
37
38
38
## Plan Color Strategy
39
39
40
-
Create a purposeful color introduction plan.
40
+
Create purposeful color introduction plan.
41
41
42
42
- **Color palette**: What colors match brand or context? (Choose 2-4 colors max beyond neutrals)
43
43
- **Dominant color**: Which color owns 60% of colored elements?
···
74
74
- **Gradient backgrounds**: Add depth with subtle, intentional gradients (not generic purple-blue)
75
75
- **Cards and surfaces**: Tint cards or surfaces slightly for warmth
76
76
77
-
**Use OKLCH for color**: It is perceptually uniform, meaning equal steps in lightness look equal. Great for generating harmonious scales.
77
+
**Use OKLCH for color**: it's perceptually uniform, meaning equal steps in lightness look equal. Great for generating harmonious scales.
78
78
79
79
### Data Visualization
80
80
- **Charts and graphs**: Use color to encode categories or values
···
131
131
132
132
## Verify Color Addition
133
133
134
-
Test that colorization improves the experience.
134
+
Test that colorization improves experience.
135
135
136
136
- **Better hierarchy**: Does color guide attention appropriately?
137
137
- **Clearer meaning**: Does color help users understand states or categories?
-142
skills/colorize/SKILL.md.original.md
-142
skills/colorize/SKILL.md.original.md
···
1
-
---
2
-
name: colorize
3
-
description: "Add strategic color to features that are too monochromatic or lack visual interest, making interfaces more engaging and expressive. Use when the user mentions the design looking gray, dull, lacking warmth, needing more color, or wanting a more vibrant or expressive palette."
4
-
argument-hint: "[target]"
5
-
user-invocable: true
6
-
---
7
-
8
-
Strategically introduce color to designs that are too monochromatic, gray, or lacking in visual warmth and personality.
9
-
10
-
## MANDATORY PREPARATION
11
-
12
-
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. Additionally gather: existing brand colors.
13
-
14
-
---
15
-
16
-
## Assess Color Opportunity
17
-
18
-
Analyze the current state and identify opportunities.
19
-
20
-
### 1. Understand current state
21
-
- **Color absence**: Pure grayscale? Limited neutrals? One timid accent?
22
-
- **Missed opportunities**: Where could color add meaning, hierarchy, or delight?
23
-
- **Context**: What is appropriate for this domain and audience?
24
-
- **Brand**: Are there existing brand colors we should use?
25
-
26
-
### 2. Identify where color adds value
27
-
- **Semantic meaning**: Success (green), error (red), warning (yellow or orange), info (blue)
28
-
- **Hierarchy**: Drawing attention to important elements
29
-
- **Categorization**: Different sections, types, or states
30
-
- **Emotional tone**: Warmth, energy, trust, creativity
31
-
- **Wayfinding**: Helping users navigate and understand structure
32
-
- **Delight**: Moments of visual interest and personality
33
-
34
-
If any of these are unclear from the codebase, {{ask_instruction}}
35
-
36
-
**CRITICAL**: More color does not equal better. Strategic color beats rainbow vomit every time. Every color should have a purpose.
37
-
38
-
## Plan Color Strategy
39
-
40
-
Create a purposeful color introduction plan.
41
-
42
-
- **Color palette**: What colors match the brand or context? (Choose 2-4 colors max beyond neutrals)
43
-
- **Dominant color**: Which color owns 60% of colored elements?
44
-
- **Accent colors**: Which colors provide contrast and highlights? (30% and 10%)
45
-
- **Application strategy**: Where does each color appear and why?
46
-
47
-
**IMPORTANT**: Color should enhance hierarchy and meaning, not create chaos. Less is more when it matters more.
48
-
49
-
## Introduce Color Strategically
50
-
51
-
Add color systematically across these dimensions.
52
-
53
-
### Semantic Color
54
-
- **State indicators**:
55
-
- Success: Green tones (emerald, forest, mint)
56
-
- Error: Red or pink tones (rose, crimson, coral)
57
-
- Warning: Orange or amber tones
58
-
- Info: Blue tones (sky, ocean, indigo)
59
-
- Neutral: Gray or slate for inactive states
60
-
61
-
- **Status badges**: Colored backgrounds or borders for states (active, pending, completed, etc.)
62
-
- **Progress indicators**: Colored bars, rings, or charts showing completion or health
63
-
64
-
### Accent Color Application
65
-
- **Primary actions**: Color the most important buttons or CTAs
66
-
- **Links**: Add color to clickable text (maintain accessibility)
67
-
- **Icons**: Colorize key icons for recognition and personality
68
-
- **Headers or titles**: Add color to section headers or key labels
69
-
- **Hover states**: Introduce color on interaction
70
-
71
-
### Background and Surfaces
72
-
- **Tinted backgrounds**: Replace pure gray (#f5f5f5) with warm neutrals (oklch(97% 0.01 60)) or cool tints (oklch(97% 0.01 250))
73
-
- **Colored sections**: Use subtle background colors to separate areas
74
-
- **Gradient backgrounds**: Add depth with subtle, intentional gradients (not generic purple-blue)
75
-
- **Cards and surfaces**: Tint cards or surfaces slightly for warmth
76
-
77
-
**Use OKLCH for color**: It is perceptually uniform, meaning equal steps in lightness look equal. Great for generating harmonious scales.
78
-
79
-
### Data Visualization
80
-
- **Charts and graphs**: Use color to encode categories or values
81
-
- **Heatmaps**: Color intensity shows density or importance
82
-
- **Comparison**: Color coding for different datasets or timeframes
83
-
84
-
### Borders and Accents
85
-
- **Accent borders**: Add colored left or top borders to cards or sections
86
-
- **Underlines**: Color underlines for emphasis or active states
87
-
- **Dividers**: Subtle colored dividers instead of gray lines
88
-
- **Focus rings**: Colored focus indicators matching brand
89
-
90
-
### Typography Color
91
-
- **Colored headings**: Use brand colors for section headings (maintain contrast)
92
-
- **Highlight text**: Color for emphasis or categories
93
-
- **Labels and tags**: Small colored labels for metadata or categories
94
-
95
-
### Decorative Elements
96
-
- **Illustrations**: Add colored illustrations or icons
97
-
- **Shapes**: Geometric shapes in brand colors as background elements
98
-
- **Gradients**: Colorful gradient overlays or mesh backgrounds
99
-
- **Blobs or organic shapes**: Soft colored shapes for visual interest
100
-
101
-
## Balance and Refinement
102
-
103
-
Ensure color addition improves rather than overwhelms.
104
-
105
-
### Maintain Hierarchy
106
-
- **Dominant color** (60%): Primary brand color or most used accent
107
-
- **Secondary color** (30%): Supporting color for variety
108
-
- **Accent color** (10%): High contrast for key moments
109
-
- **Neutrals** (remaining): Gray, black, white for structure
110
-
111
-
### Accessibility
112
-
- **Contrast ratios**: Ensure WCAG compliance (4.5:1 for text, 3:1 for UI components)
113
-
- **Do not rely on color alone**: Use icons, labels, or patterns alongside color
114
-
- **Test for color blindness**: Verify red and green combinations work for all users
115
-
116
-
### Cohesion
117
-
- **Consistent palette**: Use colors from defined palette, not arbitrary choices
118
-
- **Systematic application**: Same color meanings throughout (green always equals success)
119
-
- **Temperature consistency**: Warm palette stays warm, cool stays cool
120
-
121
-
**NEVER**:
122
-
- Use every color in the rainbow (choose 2-4 colors beyond neutrals)
123
-
- Apply color randomly without semantic meaning
124
-
- Put gray text on colored backgrounds. It looks washed out. Use a darker shade of the background color or transparency instead.
125
-
- Use pure gray for neutrals. Add subtle color tint (warm or cool) for sophistication.
126
-
- Use pure black (#000) or pure white (#fff) for large areas.
127
-
- Violate WCAG contrast requirements
128
-
- Use color as the only indicator (accessibility issue)
129
-
- Make everything colorful (defeats the purpose)
130
-
- Default to purple-blue gradients (AI slop aesthetic)
131
-
132
-
## Verify Color Addition
133
-
134
-
Test that colorization improves the experience.
135
-
136
-
- **Better hierarchy**: Does color guide attention appropriately?
137
-
- **Clearer meaning**: Does color help users understand states or categories?
138
-
- **More engaging**: Does the interface feel warmer and more inviting?
139
-
- **Still accessible**: Do all color combinations meet WCAG standards?
140
-
- **Not overwhelming**: Is color balanced and purposeful?
141
-
142
-
Remember: Color is emotional and powerful. Use it to create warmth, guide attention, communicate meaning, and express personality. But restraint and strategy matter more than saturation and variety. Be colorful, but be intentional.
+16
-16
skills/compress/SKILL.md
+16
-16
skills/compress/SKILL.md
···
1
1
---
2
2
name: compress
3
3
description: >
4
-
Compress natural language memory files (CLAUDE.md, todos, preferences) into caveman format
5
-
to save input tokens. Preserves all technical substance, code, URLs, and structure.
6
-
Compressed version overwrites the original file. Human-readable backup saved as FILE.original.md.
7
-
Trigger: /caveman:compress FILEPATH or "compress memory file"
4
+
Compress natural language memory files (CLAUDE.md, todos, preferences) into caveman format
5
+
to save input tokens. Preserves all technical substance, code, URLs, and structure.
6
+
Compressed version overwrites original file. Human-readable backup saved as FILE.original.md.
7
+
Trigger: /caveman:compress FILEPATH or "compress memory file"
8
8
---
9
9
10
10
# Caveman Compress
···
15
15
16
16
## Trigger
17
17
18
-
`/caveman:compress <filepath>` or when user asks to compress a memory file.
18
+
`/caveman:compress <filepath>` or when user asks to compress memory file.
19
19
20
20
## Process
21
21
22
-
1. This SKILL.md lives alongside `scripts/` in the same directory. Find that directory.
22
+
1. This SKILL.md lives alongside `scripts/` in same directory. Find that directory.
23
23
24
24
2. Run:
25
25
26
26
cd <directory_containing_this_SKILL.md> && python3 -m scripts <absolute_filepath>
27
27
28
-
3. The CLI will:
28
+
3. CLI will:
29
29
- detect file type (no tokens)
30
30
- call Claude to compress
31
31
- validate output (no tokens)
···
43
43
- Pleasantries: "sure", "certainly", "of course", "happy to", "I'd recommend"
44
44
- Hedging: "it might be worth", "you could consider", "it would be good to"
45
45
- Redundant phrasing: "in order to" → "to", "make sure to" → "ensure", "the reason is because" → "because"
46
-
- Connective fluff: "however", "furthermore", "additionally", "in addition"
46
+
- Connective fluff: however, furthermore, additionally, in addition
47
47
48
48
### Preserve EXACTLY (never modify)
49
49
- Code blocks (fenced ``` and indented)
···
66
66
### Compress
67
67
- Use short synonyms: "big" not "extensive", "fix" not "implement a solution for", "use" not "utilize"
68
68
- Fragments OK: "Run tests before commit" not "You should always run tests before committing"
69
-
- Drop "you should", "make sure to", "remember to" — just state the action
70
-
- Merge redundant bullets that say the same thing differently
71
-
- Keep one example where multiple examples show the same pattern
69
+
- Drop "you should", "make sure to", "remember to"; state action
70
+
- Merge redundant bullets that say same thing differently
71
+
- Keep one example where multiple examples show same pattern
72
72
73
73
CRITICAL RULE:
74
74
Anything inside ``` ... ``` must be copied EXACTLY.
···
90
90
## Pattern
91
91
92
92
Original:
93
-
> You should always make sure to run the test suite before pushing any changes to the main branch. This is important because it helps catch bugs early and prevents broken builds from being deployed to production.
93
+
> always ensure run test suite before pushing any changes to main branch. This is important because it helps catch bugs early and prevents broken builds from being deployed to production.
94
94
95
95
Compressed:
96
96
> Run tests before push to main. Catch bugs early, prevent broken prod deploys.
97
97
98
98
Original:
99
-
> The application uses a microservices architecture with the following components. The API gateway handles all incoming requests and routes them to the appropriate service. The authentication service is responsible for managing user sessions and JWT tokens.
99
+
> application uses microservices architecture with following components. API gateway handles all incoming requests and routes them to appropriate service. authentication service is responsible for managing user sessions and JWT tokens.
100
100
101
101
Compressed:
102
102
> Microservices architecture. API gateway route all requests to services. Auth service manage user sessions + JWT tokens.
103
103
104
104
## Boundaries
105
105
106
-
- ONLY compress natural language files (.md, .txt, .typ, .typst, .tex, extensionless)
107
-
- NEVER modify: .py, .js, .ts, .json, .yaml, .yml, .toml, .env, .lock, .css, .html, .xml, .sql, .sh
108
-
- If file has mixed content (prose + code), compress ONLY the prose sections
106
+
- ONLY compress natural language files (.md,.txt,.typ,.typst,.tex, extensionless)
107
+
- NEVER modify:.py,.js,.ts,.json,.yaml,.yml,.toml,.env,.lock,.css,.html,.xml,.sql,.sh
108
+
- If file has mixed content (prose + code), compress ONLY prose sections
109
109
- If unsure whether something is code or prose, leave it unchanged
110
110
- Original file is backed up as FILE.original.md before overwriting
111
111
- Never compress FILE.original.md (skip it)
+27
-27
skills/critique/SKILL.md
+27
-27
skills/critique/SKILL.md
···
1
1
---
2
2
name: critique
3
-
description: "Evaluate design from a UX perspective, assessing visual hierarchy, information architecture, emotional resonance, cognitive load, and overall quality with quantitative scoring, persona-based testing, and actionable feedback. Use when the user asks to review, critique, evaluate, or give feedback on a design or component."
3
+
description: "Evaluate design from UX perspective, assessing visual hierarchy, information architecture, emotional resonance, cognitive load, and overall quality with quantitative scoring, persona-based testing, and actionable feedback. Use when user asks to review, critique, evaluate, or give feedback on design or component."
4
4
argument-hint: "[area (feature, page, component...)]"
5
5
user-invocable: true
6
6
---
7
7
8
8
## MANDATORY PREPARATION
9
9
10
-
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. gather: what the interface is trying to accomplish.
10
+
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and Context Gathering Protocol. Follow protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. gather: what interface is trying to accomplish.
11
11
12
12
---
13
13
14
-
Conduct a holistic design critique, evaluating whether the interface works: not technically, but as a designed experience. Think like a design director giving feedback.
14
+
Conduct holistic design critique, evaluating whether interface works: not technically, but as designed experience. Think like design director giving feedback.
15
15
16
16
## Phase 1: Design Critique
17
17
18
-
Evaluate the interface across these dimensions.
18
+
Evaluate interface across these dimensions.
19
19
20
20
### 1. AI Slop Detection (CRITICAL)
21
21
22
-
**This is the most important check.** Does this look like every other AI-generated interface from 2024-2025?
22
+
**This is most important check.** Does this look like every other AI-generated interface from 2024-2025?
23
23
24
-
Review the design against ALL the DO NOT guidelines in the frontend-design skill. They are the fingerprints of AI-generated work. Check for the AI color palette, gradient text, dark mode with glowing accents, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells.
24
+
Review design against ALL DO NOT guidelines in frontend-design skill. They are fingerprints of AI-generated work. Check for AI color palette, gradient text, dark mode with glowing accents, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells.
25
25
26
-
**The test**: If you showed this to someone and said "AI made this," would they believe you immediately? If yes, that is the problem.
26
+
** test**: If you showed this to someone and said "AI made this," would they believe you immediately? If yes, that is problem.
27
27
28
28
### 2. Visual Hierarchy
29
29
- Does eye flow to most important element first?
···
32
32
- Is there visual competition between elements that should have different weights?
33
33
34
34
### 3. Information Architecture and Cognitive Load
35
-
> *Consult [cognitive-load](reference/cognitive-load.md) for the working memory rule and 8-item checklist*
35
+
> *Consult [cognitive-load](reference/cognitive-load.md) for working memory rule and 8-item checklist*
36
36
- Is structure intuitive? Would new user understand organization?
37
37
- Is related content grouped logically?
38
38
- Are there too many choices at once? Count visible options at each decision point. If more than 4, flag it.
···
87
87
88
88
## Phase 2: Present Findings
89
89
90
-
Structure your feedback as a design director would.
90
+
Structure your feedback as design director would.
91
91
92
92
### Design Health Score
93
93
> *Consult [heuristics-scoring](reference/heuristics-scoring.md)*
94
94
95
-
Score each of Nielsen 10 heuristics 0-4. Present as a table:
95
+
Score each of Nielsen 10 heuristics 0-4. Present as table:
96
96
97
97
| # | Heuristic | Score | Key Issue |
98
98
|---|-----------|-------|-----------|
···
108
108
| 10 | Help and Documentation | ? | |
109
109
| **Total** | | **??/40** | **[Rating band]** |
110
110
111
-
Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20-32.
111
+
Be honest with scores. 4 means genuinely excellent. Most real interfaces score 20-32.
112
112
113
113
### Anti-Patterns Verdict
114
-
**Start here.** Pass or fail: Does this look AI-generated? List specific tells from the skill Anti-Patterns section. Be brutally honest.
114
+
**Start here.** Pass or fail: Does this look AI-generated? List specific tells from skill Anti-Patterns section. Be brutally honest.
115
115
116
116
### Overall Impression
117
-
A brief gut reaction: what works, what does not, and the single biggest opportunity.
117
+
brief gut reaction: what works, what does not, and single biggest opportunity.
118
118
119
119
### What is Working
120
120
Highlight 2-3 things done well. Be specific about why they work.
121
121
122
122
### Priority Issues
123
-
The 3-5 most impactful design problems, ordered by importance.
123
+
3-5 most impactful design problems, ordered by importance.
124
124
125
125
For each issue, tag with P0-P3 severity (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions):
126
126
- **[P?] What**: Name problem clearly
···
131
131
### Persona Red Flags
132
132
> *Consult [personas](reference/personas.md)*
133
133
134
-
Auto-select 2-3 personas most relevant to this interface type (use the selection table in the reference). If {{config_file}} contains a Design Context section from teach-impeccable, also generate 1-2 project-specific personas from the audience or brand info.
134
+
Auto-select 2-3 personas most relevant to this interface type (use selection table in reference). If {{config_file}} contains Design Context section from teach-impeccable, also generate 1-2 project-specific personas from audience or brand info.
135
135
136
-
For each selected persona, walk through the primary user action and list specific red flags found:
136
+
For each selected persona, walk through primary user action and list specific red flags found:
137
137
138
138
**Alex (Power User)**: No keyboard shortcuts detected. Form requires 8 clicks for primary action. Forced modal onboarding. High abandonment risk.
139
139
140
140
**Jordan (First-Timer)**: Icon-only nav in sidebar. Technical jargon in error messages ("404 Not Found"). No visible help. Will abandon at step 2.
141
141
142
-
Be specific. Name the exact elements and interactions that fail each persona. Do not write generic persona descriptions. Write what broke for them.
142
+
Be specific. Name exact elements and interactions that fail each persona. Do not write generic persona descriptions. Write what broke for them.
143
143
144
144
### Minor Observations
145
145
Quick notes on smaller issues worth addressing.
···
154
154
155
155
## Phase 3: Ask the User
156
156
157
-
**After presenting findings**, use targeted questions based on what was found. {{ask_instruction}} These answers will shape the action plan.
157
+
**After presenting findings**, use targeted questions based on what was found. {{ask_instruction}} These answers will shape action plan.
158
158
159
-
Ask questions along these lines (adapt to the specific findings: do NOT ask generic questions):
159
+
Ask questions along these lines (adapt to specific findings: do NOT ask generic questions):
160
160
161
-
1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2-3 issue categories as options.
161
+
1. **Priority direction**: Based on issues found, ask which category matters most to user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer top 2-3 issue categories as options.
162
162
163
-
2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer, bolder, more playful?" Offer 2-3 tonal directions as options based on what would fix the issues found.
163
+
2. **Design intent**: If critique found tonal mismatch, ask whether it was intentional. For example: " interface feels clinical and corporate. Is that intended tone, or should it feel warmer, bolder, more playful?" Offer 2-3 tonal directions as options based on what would fix issues found.
164
164
165
-
3. **Scope**: Ask how much the user wants to take on. For example: "I found N issues. Want to address everything, or focus on the top 3?" Offer scope options like "Top 3 only", "All issues", "Critical issues only".
165
+
3. **Scope**: Ask how much user wants to take on. For example: "I found N issues. Want to address everything, or focus on top 3?" Offer scope options like "Top 3 only", "All issues", "Critical issues only".
166
166
167
-
4. **Constraints** (optional: only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done.
167
+
4. **Constraints** (optional: only ask if relevant): If findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents plan from touching things user considers done.
168
168
169
169
**Rules for questions**:
170
170
- Every question must reference specific findings from Phase 2. Never ask generic "who is your audience?" questions
···
174
174
175
175
## Phase 4: Recommended Actions
176
176
177
-
**After receiving the user answers**, present a prioritized action summary reflecting the user priorities and scope from Phase 3.
177
+
**After receiving user answers**, present prioritized action summary reflecting user priorities and scope from Phase 3.
178
178
179
179
### Action Summary
180
180
181
-
List recommended commands in priority order, based on the user answers:
181
+
List recommended commands in priority order, based on user answers:
182
182
183
183
1. **`{{command_prefix}}command-name`**: Brief description of what to fix (specific context from critique findings)
184
184
2. **`{{command_prefix}}command-name`**: Brief description (specific context)
···
194
194
- If user marked areas as off-limits, exclude commands that would touch those areas
195
195
- End with {{command_prefix}}polish as final step if any fixes were recommended
196
196
197
-
After presenting the summary, tell the user:
197
+
After presenting summary, tell user:
198
198
199
-
> You can ask me to run these one at a time, all at once, or in any order you prefer.
199
+
> ask me to run these one at time, all at once, or in any order you prefer.
200
200
>
201
201
> Re-run {{command_prefix}}critique after fixes to see your score improve.
-201
skills/critique/SKILL.md.original.md
-201
skills/critique/SKILL.md.original.md
···
1
-
---
2
-
name: critique
3
-
description: "Evaluate design from a UX perspective, assessing visual hierarchy, information architecture, emotional resonance, cognitive load, and overall quality with quantitative scoring, persona-based testing, and actionable feedback. Use when the user asks to review, critique, evaluate, or give feedback on a design or component."
4
-
argument-hint: "[area (feature, page, component...)]"
5
-
user-invocable: true
6
-
---
7
-
8
-
## MANDATORY PREPARATION
9
-
10
-
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. Additionally gather: what the interface is trying to accomplish.
11
-
12
-
---
13
-
14
-
Conduct a holistic design critique, evaluating whether the interface actually works: not just technically, but as a designed experience. Think like a design director giving feedback.
15
-
16
-
## Phase 1: Design Critique
17
-
18
-
Evaluate the interface across these dimensions.
19
-
20
-
### 1. AI Slop Detection (CRITICAL)
21
-
22
-
**This is the most important check.** Does this look like every other AI-generated interface from 2024-2025?
23
-
24
-
Review the design against ALL the DO NOT guidelines in the frontend-design skill. They are the fingerprints of AI-generated work. Check for the AI color palette, gradient text, dark mode with glowing accents, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells.
25
-
26
-
**The test**: If you showed this to someone and said "AI made this," would they believe you immediately? If yes, that is the problem.
27
-
28
-
### 2. Visual Hierarchy
29
-
- Does the eye flow to the most important element first?
30
-
- Is there a clear primary action? Can you spot it in 2 seconds?
31
-
- Do size, color, and position communicate importance correctly?
32
-
- Is there visual competition between elements that should have different weights?
33
-
34
-
### 3. Information Architecture and Cognitive Load
35
-
> *Consult [cognitive-load](reference/cognitive-load.md) for the working memory rule and 8-item checklist*
36
-
- Is the structure intuitive? Would a new user understand the organization?
37
-
- Is related content grouped logically?
38
-
- Are there too many choices at once? Count visible options at each decision point. If more than 4, flag it.
39
-
- Is the navigation clear and predictable?
40
-
- **Progressive disclosure**: Is complexity revealed only when needed, or dumped on the user upfront?
41
-
- **Run the 8-item cognitive load checklist** from the reference. Report failure count: 0-1 equals low (good), 2-3 equals moderate, 4+ equals critical.
42
-
43
-
### 4. Emotional Journey
44
-
- What emotion does this interface evoke? Is that intentional?
45
-
- Does it match the brand personality?
46
-
- Does it feel trustworthy, approachable, premium, playful: whatever it should feel?
47
-
- Would the target user feel "this is for me"?
48
-
- **Peak-end rule**: Is the most intense moment positive? Does the experience end well (confirmation, celebration, clear next step)?
49
-
- **Emotional valleys**: Check for onboarding frustration, error cliffs, feature discovery gaps, or anxiety spikes at high-stakes moments (payment, delete, commit)
50
-
- **Interventions at negative moments**: Are there design interventions where users are likely to feel frustrated or anxious? (progress indicators, reassurance copy, undo options, social proof)
51
-
52
-
### 5. Discoverability and Affordance
53
-
- Are interactive elements obviously interactive?
54
-
- Would a user know what to do without instructions?
55
-
- Are hover and focus states providing useful feedback?
56
-
- Are there hidden features that should be more visible?
57
-
58
-
### 6. Composition and Balance
59
-
- Does the layout feel balanced or uncomfortably weighted?
60
-
- Is whitespace used intentionally or just leftover?
61
-
- Is there visual rhythm in spacing and repetition?
62
-
- Does asymmetry feel designed or accidental?
63
-
64
-
### 7. Typography as Communication
65
-
- Does the type hierarchy clearly signal what to read first, second, third?
66
-
- Is body text comfortable to read? (line length, spacing, size)
67
-
- Do font choices reinforce the brand or tone?
68
-
- Is there enough contrast between heading levels?
69
-
70
-
### 8. Color with Purpose
71
-
- Is color used to communicate, not just decorate?
72
-
- Does the palette feel cohesive?
73
-
- Are accent colors drawing attention to the right things?
74
-
- Does it work for colorblind users? (not just technically: does meaning still come through?)
75
-
76
-
### 9. States and Edge Cases
77
-
- Empty states: Do they guide users toward action, or just say "nothing here"?
78
-
- Loading states: Do they reduce perceived wait time?
79
-
- Error states: Are they helpful and non-blaming?
80
-
- Success states: Do they confirm and guide next steps?
81
-
82
-
### 10. Microcopy and Voice
83
-
- Is the writing clear and concise?
84
-
- Does it sound like a human (the right human for this brand)?
85
-
- Are labels and buttons unambiguous?
86
-
- Does error copy help users fix the problem?
87
-
88
-
## Phase 2: Present Findings
89
-
90
-
Structure your feedback as a design director would.
91
-
92
-
### Design Health Score
93
-
> *Consult [heuristics-scoring](reference/heuristics-scoring.md)*
94
-
95
-
Score each of Nielsen 10 heuristics 0-4. Present as a table:
96
-
97
-
| # | Heuristic | Score | Key Issue |
98
-
|---|-----------|-------|-----------|
99
-
| 1 | Visibility of System Status | ? | [specific finding or "—" if solid] |
100
-
| 2 | Match System and Real World | ? | |
101
-
| 3 | User Control and Freedom | ? | |
102
-
| 4 | Consistency and Standards | ? | |
103
-
| 5 | Error Prevention | ? | |
104
-
| 6 | Recognition Rather Than Recall | ? | |
105
-
| 7 | Flexibility and Efficiency | ? | |
106
-
| 8 | Aesthetic and Minimalist Design | ? | |
107
-
| 9 | Error Recovery | ? | |
108
-
| 10 | Help and Documentation | ? | |
109
-
| **Total** | | **??/40** | **[Rating band]** |
110
-
111
-
Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20-32.
112
-
113
-
### Anti-Patterns Verdict
114
-
**Start here.** Pass or fail: Does this look AI-generated? List specific tells from the skill Anti-Patterns section. Be brutally honest.
115
-
116
-
### Overall Impression
117
-
A brief gut reaction: what works, what does not, and the single biggest opportunity.
118
-
119
-
### What is Working
120
-
Highlight 2-3 things done well. Be specific about why they work.
121
-
122
-
### Priority Issues
123
-
The 3-5 most impactful design problems, ordered by importance.
124
-
125
-
For each issue, tag with P0-P3 severity (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions):
126
-
- **[P?] What**: Name the problem clearly
127
-
- **Why it matters**: How this hurts users or undermines goals
128
-
- **Fix**: What to do about it (be concrete)
129
-
- **Suggested command**: Which command could address this (from: {{available_commands}})
130
-
131
-
### Persona Red Flags
132
-
> *Consult [personas](reference/personas.md)*
133
-
134
-
Auto-select 2-3 personas most relevant to this interface type (use the selection table in the reference). If {{config_file}} contains a Design Context section from teach-impeccable, also generate 1-2 project-specific personas from the audience or brand info.
135
-
136
-
For each selected persona, walk through the primary user action and list specific red flags found:
137
-
138
-
**Alex (Power User)**: No keyboard shortcuts detected. Form requires 8 clicks for primary action. Forced modal onboarding. High abandonment risk.
139
-
140
-
**Jordan (First-Timer)**: Icon-only nav in sidebar. Technical jargon in error messages ("404 Not Found"). No visible help. Will abandon at step 2.
141
-
142
-
Be specific. Name the exact elements and interactions that fail each persona. Do not write generic persona descriptions. Write what broke for them.
143
-
144
-
### Minor Observations
145
-
Quick notes on smaller issues worth addressing.
146
-
147
-
**Remember**:
148
-
- Be direct. Vague feedback wastes everyone time.
149
-
- Be specific. "the submit button" not "some elements"
150
-
- Say what is wrong AND why it matters to users
151
-
- Give concrete suggestions, not just "consider exploring..."
152
-
- Prioritize ruthlessly. If everything is important, nothing is.
153
-
- Do not soften criticism. Developers need honest feedback to ship great design.
154
-
155
-
## Phase 3: Ask the User
156
-
157
-
**After presenting findings**, use targeted questions based on what was actually found. {{ask_instruction}} These answers will shape the action plan.
158
-
159
-
Ask questions along these lines (adapt to the specific findings: do NOT ask generic questions):
160
-
161
-
1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2-3 issue categories as options.
162
-
163
-
2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer, bolder, more playful?" Offer 2-3 tonal directions as options based on what would fix the issues found.
164
-
165
-
3. **Scope**: Ask how much the user wants to take on. For example: "I found N issues. Want to address everything, or focus on the top 3?" Offer scope options like "Top 3 only", "All issues", "Critical issues only".
166
-
167
-
4. **Constraints** (optional: only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done.
168
-
169
-
**Rules for questions**:
170
-
- Every question must reference specific findings from Phase 2. Never ask generic "who is your audience?" questions
171
-
- Keep it to 2-4 questions maximum. Respect the user time.
172
-
- Offer concrete options, not open-ended prompts.
173
-
- If findings are straightforward (e.g., only 1-2 clear issues), skip questions and go directly to Phase 4
174
-
175
-
## Phase 4: Recommended Actions
176
-
177
-
**After receiving the user answers**, present a prioritized action summary reflecting the user priorities and scope from Phase 3.
178
-
179
-
### Action Summary
180
-
181
-
List recommended commands in priority order, based on the user answers:
182
-
183
-
1. **`{{command_prefix}}command-name`**: Brief description of what to fix (specific context from critique findings)
184
-
2. **`{{command_prefix}}command-name`**: Brief description (specific context)
185
-
...
186
-
187
-
**Rules for recommendations**:
188
-
- Only recommend commands from: {{available_commands}}
189
-
- Order by the user stated priorities first, then by impact
190
-
- Each item description should carry enough context that the command knows what to focus on
191
-
- Map each Priority Issue to the appropriate command
192
-
- Skip commands that would address zero issues
193
-
- If the user chose a limited scope, only include items within that scope
194
-
- If the user marked areas as off-limits, exclude commands that would touch those areas
195
-
- End with {{command_prefix}}polish as the final step if any fixes were recommended
196
-
197
-
After presenting the summary, tell the user:
198
-
199
-
> You can ask me to run these one at a time, all at once, or in any order you prefer.
200
-
>
201
-
> Re-run {{command_prefix}}critique after fixes to see your score improve.
+7
-7
skills/delight/SKILL.md
+7
-7
skills/delight/SKILL.md
···
1
1
---
2
2
name: delight
3
-
description: "Add moments of joy, personality, and unexpected touches that make interfaces memorable and enjoyable to use. Elevates functional to delightful. Use when the user asks to add polish, personality, animations, micro-interactions, delight, or make an interface feel fun or memorable."
3
+
description: "Add moments of joy, personality, and unexpected touches that make interfaces memorable and enjoyable to use. Elevates functional to delightful. Use when user asks to add polish, personality, animations, micro-interactions, delight, or make interface feel fun or memorable."
4
4
argument-hint: "[target]"
5
5
user-invocable: true
6
6
---
···
9
9
10
10
## MANDATORY PREPARATION
11
11
12
-
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. gather: what is appropriate for the domain (playful vs professional vs quirky vs elegant).
12
+
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and Context Gathering Protocol. Follow protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. gather: what is appropriate for domain (playful vs professional vs quirky vs elegant).
13
13
14
14
---
15
15
16
16
## Assess Delight Opportunities
17
17
18
-
Identify where delight would enhance (not distract from) the experience.
18
+
Identify where delight would enhance (not distract from) experience.
19
19
20
20
### 1. Find natural delight moments
21
21
- **Success states**: Completed actions (save, send, publish)
···
38
38
- **Helpful surprises**: Anticipating needs before users ask (productivity tools)
39
39
- **Sensory richness**: Satisfying sounds, smooth animations (creative tools)
40
40
41
-
If any of these are unclear from the codebase, {{ask_instruction}}
41
+
If any of these are unclear from codebase, {{ask_instruction}}
42
42
43
-
**CRITICAL**: Delight should enhance usability, never obscure it. If users notice the delight more than accomplishing their goal, you have gone too far.
43
+
**CRITICAL**: Delight should enhance usability, never obscure it. If users notice delight more than accomplishing their goal, you have gone too far.
44
44
45
45
## Delight Principles
46
46
···
244
244
- "Checking for updates since yesterday..."
245
245
```
246
246
247
-
**WARNING**: Avoid cliched loading messages like "Herding pixels", "Teaching robots to dance", "Consulting the magic 8-ball", "Counting backwards from infinity". These are AI-slop copy: instantly recognizable as machine-generated. Write messages that are specific to what your product does.
247
+
**WARNING**: Avoid cliched loading messages like "Herding pixels", "Teaching robots to dance", "Consulting magic 8-ball", "Counting backwards from infinity". These are AI-slop copy: instantly recognizable as machine-generated. Write messages that are specific to what your product does.
248
248
249
249
### Celebration Moments
250
250
···
300
300
- **Appropriate**: Matches brand and context
301
301
- **Accessible**: Works with reduced motion, screen readers
302
302
303
-
Remember: Delight is the difference between a tool and an experience. Add personality, surprise users positively, and create moments worth sharing. But always respect usability: delight should enhance, never obstruct.
303
+
Remember: Delight is difference between tool and experience. Add personality, surprise users positively, and create moments worth sharing. But always respect usability: delight should enhance, never obstruct.
-303
skills/delight/SKILL.md.original.md
-303
skills/delight/SKILL.md.original.md
···
1
-
---
2
-
name: delight
3
-
description: "Add moments of joy, personality, and unexpected touches that make interfaces memorable and enjoyable to use. Elevates functional to delightful. Use when the user asks to add polish, personality, animations, micro-interactions, delight, or make an interface feel fun or memorable."
4
-
argument-hint: "[target]"
5
-
user-invocable: true
6
-
---
7
-
8
-
Identify opportunities to add moments of joy, personality, and unexpected polish that transform functional interfaces into delightful experiences.
9
-
10
-
## MANDATORY PREPARATION
11
-
12
-
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. Additionally gather: what is appropriate for the domain (playful vs professional vs quirky vs elegant).
13
-
14
-
---
15
-
16
-
## Assess Delight Opportunities
17
-
18
-
Identify where delight would enhance (not distract from) the experience.
19
-
20
-
### 1. Find natural delight moments
21
-
- **Success states**: Completed actions (save, send, publish)
22
-
- **Empty states**: First-time experiences, onboarding
23
-
- **Loading states**: Waiting periods that could be entertaining
24
-
- **Achievements**: Milestones, streaks, completions
25
-
- **Interactions**: Hover states, clicks, drags
26
-
- **Errors**: Softening frustrating moments
27
-
- **Easter eggs**: Hidden discoveries for curious users
28
-
29
-
### 2. Understand the context
30
-
- What is the brand personality? (Playful? Professional? Quirky? Elegant?)
31
-
- Who is the audience? (Tech-savvy? Creative? Corporate?)
32
-
- What is the emotional context? (Accomplishment? Exploration? Frustration?)
33
-
- What is appropriate? (Banking app does not equal gaming app)
34
-
35
-
### 3. Define delight strategy
36
-
- **Subtle sophistication**: Refined micro-interactions (luxury brands)
37
-
- **Playful personality**: Whimsical illustrations and copy (consumer apps)
38
-
- **Helpful surprises**: Anticipating needs before users ask (productivity tools)
39
-
- **Sensory richness**: Satisfying sounds, smooth animations (creative tools)
40
-
41
-
If any of these are unclear from the codebase, {{ask_instruction}}
42
-
43
-
**CRITICAL**: Delight should enhance usability, never obscure it. If users notice the delight more than accomplishing their goal, you have gone too far.
44
-
45
-
## Delight Principles
46
-
47
-
Follow these guidelines.
48
-
49
-
### Delight Amplifies, Never Blocks
50
-
- Delight moments should be quick (less than 1 second)
51
-
- Never delay core functionality for delight
52
-
- Make delight skippable or subtle
53
-
- Respect user time and task focus
54
-
55
-
### Surprise and Discovery
56
-
- Hide delightful details for users to discover
57
-
- Reward exploration and curiosity
58
-
- Do not announce every delight moment
59
-
- Let users share discoveries with others
60
-
61
-
### Appropriate to Context
62
-
- Match delight to emotional moment (celebrate success, empathize with errors)
63
-
- Respect the user state (do not be playful during critical errors)
64
-
- Match brand personality and audience expectations
65
-
- Cultural sensitivity (what is delightful varies by culture)
66
-
67
-
### Compound Over Time
68
-
- Delight should remain fresh with repeated use
69
-
- Vary responses (not same animation every time)
70
-
- Reveal deeper layers with continued use
71
-
- Build anticipation through patterns
72
-
73
-
## Delight Techniques
74
-
75
-
Add personality and joy through these methods.
76
-
77
-
### Micro-interactions and Animation
78
-
79
-
**Button delight**:
80
-
```css
81
-
/* Satisfying button press */
82
-
.button {
83
-
transition: transform 0.1s, box-shadow 0.1s;
84
-
}
85
-
.button:active {
86
-
transform: translateY(2px);
87
-
box-shadow: 0 2px 4px rgba(0,0,0,0.2);
88
-
}
89
-
90
-
/* Ripple effect on click */
91
-
/* Smooth lift on hover */
92
-
.button:hover {
93
-
transform: translateY(-2px);
94
-
transition: transform 0.2s cubic-bezier(0.25, 1, 0.5, 1); /* ease-out-quart */
95
-
}
96
-
```
97
-
98
-
**Loading delight**:
99
-
- Playful loading animations (not just spinners)
100
-
- Personality in loading messages (write product-specific ones, not generic AI filler)
101
-
- Progress indication with encouraging messages
102
-
- Skeleton screens with subtle animations
103
-
104
-
**Success animations**:
105
-
- Checkmark draw animation
106
-
- Confetti burst for major achievements
107
-
- Gentle scale and fade for confirmation
108
-
- Satisfying sound effects (subtle)
109
-
110
-
**Hover surprises**:
111
-
- Icons that animate on hover
112
-
- Color shifts or glow effects
113
-
- Tooltip reveals with personality
114
-
- Cursor changes (custom cursors for branded experiences)
115
-
116
-
### Personality in Copy
117
-
118
-
**Playful error messages**:
119
-
```
120
-
"Error 404"
121
-
"This page is playing hide and seek. (And winning)"
122
-
123
-
"Connection failed"
124
-
"Looks like the internet took a coffee break. Want to retry?"
125
-
```
126
-
127
-
**Encouraging empty states**:
128
-
```
129
-
"No projects"
130
-
"Your canvas awaits. Create something amazing."
131
-
132
-
"No messages"
133
-
"Inbox zero! You're crushing it today."
134
-
```
135
-
136
-
**Playful labels and tooltips**:
137
-
```
138
-
"Delete"
139
-
"Send to void" (for playful brand)
140
-
141
-
"Help"
142
-
"Rescue me" (tooltip)
143
-
```
144
-
145
-
**IMPORTANT**: Match copy personality to brand. Banks should not be wacky, but they can be warm.
146
-
147
-
### Illustrations and Visual Personality
148
-
149
-
**Custom illustrations**:
150
-
- Empty state illustrations (not stock icons)
151
-
- Error state illustrations (friendly monsters, quirky characters)
152
-
- Loading state illustrations (animated characters)
153
-
- Success state illustrations (celebrations)
154
-
155
-
**Icon personality**:
156
-
- Custom icon set matching brand personality
157
-
- Animated icons (subtle motion on hover or click)
158
-
- Illustrative icons (more detailed than generic)
159
-
- Consistent style across all icons
160
-
161
-
**Background effects**:
162
-
- Subtle particle effects
163
-
- Gradient mesh backgrounds
164
-
- Geometric patterns
165
-
- Parallax depth
166
-
- Time-of-day themes (morning vs night)
167
-
168
-
### Satisfying Interactions
169
-
170
-
**Drag and drop delight**:
171
-
- Lift effect on drag (shadow, scale)
172
-
- Snap animation when dropped
173
-
- Satisfying placement sound
174
-
- Undo toast ("Dropped in wrong place? [Undo]")
175
-
176
-
**Toggle switches**:
177
-
- Smooth slide with spring physics
178
-
- Color transition
179
-
- Haptic feedback on mobile
180
-
- Optional sound effect
181
-
182
-
**Progress and achievements**:
183
-
- Streak counters with celebratory milestones
184
-
- Progress bars that "celebrate" at 100%
185
-
- Badge unlocks with animation
186
-
- Playful stats ("You are on fire! 5 days in a row")
187
-
188
-
**Form interactions**:
189
-
- Input fields that animate on focus
190
-
- Checkboxes with a satisfying scale pulse when checked
191
-
- Success state that celebrates valid input
192
-
- Auto-grow textareas
193
-
194
-
### Sound Design
195
-
196
-
**Subtle audio cues** (when appropriate):
197
-
- Notification sounds (distinctive but not annoying)
198
-
- Success sounds (satisfying "ding")
199
-
- Error sounds (empathetic, not harsh)
200
-
- Typing sounds for chat or messaging
201
-
- Ambient background audio (very subtle)
202
-
203
-
**IMPORTANT**:
204
-
- Respect system sound settings
205
-
- Provide mute option
206
-
- Keep volumes quiet (subtle cues, not alarms)
207
-
- Do not play on every interaction (sound fatigue is real)
208
-
209
-
### Easter Eggs and Hidden Delights
210
-
211
-
**Discovery rewards**:
212
-
- Konami code unlocks special theme
213
-
- Hidden keyboard shortcuts (Cmd+K for special features)
214
-
- Hover reveals on logos or illustrations
215
-
- Alt text jokes on images (for screen reader users too!)
216
-
- Console messages for developers ("Like what you see? We're hiring!")
217
-
218
-
**Seasonal touches**:
219
-
- Holiday themes (subtle, tasteful)
220
-
- Seasonal color shifts
221
-
- Weather-based variations
222
-
- Time-based changes (dark at night, light during day)
223
-
224
-
**Contextual personality**:
225
-
- Different messages based on time of day
226
-
- Responses to specific user actions
227
-
- Randomized variations (not same every time)
228
-
- Progressive reveals with continued use
229
-
230
-
### Loading and Waiting States
231
-
232
-
**Make waiting engaging**:
233
-
- Interesting loading messages that rotate
234
-
- Progress bars with personality
235
-
- Mini-games during long loads
236
-
- Fun facts or tips while waiting
237
-
- Countdown with encouraging messages
238
-
239
-
```
240
-
Loading messages: write ones specific to your product, not generic AI filler:
241
-
- "Crunching your latest numbers..."
242
-
- "Syncing with your team's changes..."
243
-
- "Preparing your dashboard..."
244
-
- "Checking for updates since yesterday..."
245
-
```
246
-
247
-
**WARNING**: Avoid cliched loading messages like "Herding pixels", "Teaching robots to dance", "Consulting the magic 8-ball", "Counting backwards from infinity". These are AI-slop copy: instantly recognizable as machine-generated. Write messages that are specific to what your product actually does.
248
-
249
-
### Celebration Moments
250
-
251
-
**Success celebrations**:
252
-
- Confetti for major milestones
253
-
- Animated checkmarks for completions
254
-
- Progress bar celebrations at 100%
255
-
- "Achievement unlocked" style notifications
256
-
- Personalized messages ("You published your 10th article!")
257
-
258
-
**Milestone recognition**:
259
-
- First-time actions get special treatment
260
-
- Streak tracking and celebration
261
-
- Progress toward goals
262
-
- Anniversary celebrations
263
-
264
-
## Implementation Patterns
265
-
266
-
**Animation libraries**:
267
-
- Framer Motion (React)
268
-
- GSAP (universal)
269
-
- Lottie (After Effects animations)
270
-
- Canvas confetti (party effects)
271
-
272
-
**Sound libraries**:
273
-
- Howler.js (audio management)
274
-
- Use-sound (React hook)
275
-
276
-
**Physics libraries**:
277
-
- React Spring (spring physics)
278
-
- Popmotion (animation primitives)
279
-
280
-
**IMPORTANT**: File size matters. Compress images, optimize animations, lazy load delight features.
281
-
282
-
**NEVER**:
283
-
- Delay core functionality for delight
284
-
- Force users through delightful moments (make skippable)
285
-
- Use delight to hide poor UX
286
-
- Overdo it (less is more)
287
-
- Ignore accessibility (animate responsibly, provide alternatives)
288
-
- Make every interaction delightful (special moments should be special)
289
-
- Sacrifice performance for delight
290
-
- Be inappropriate for context (read the room)
291
-
292
-
## Verify Delight Quality
293
-
294
-
Test that delight actually delights.
295
-
296
-
- **User reactions**: Do users smile? Share screenshots?
297
-
- **Does not annoy**: Still pleasant after 100th time?
298
-
- **Does not block**: Can users opt out or skip?
299
-
- **Performant**: No jank, no slowdown
300
-
- **Appropriate**: Matches brand and context
301
-
- **Accessible**: Works with reduced motion, screen readers
302
-
303
-
Remember: Delight is the difference between a tool and an experience. Add personality, surprise users positively, and create moments worth sharing. But always respect usability: delight should enhance, never obstruct.
+9
-9
skills/distill/SKILL.md
+9
-9
skills/distill/SKILL.md
···
1
1
---
2
2
name: distill
3
-
description: "Strip designs to their essence by removing unnecessary complexity. Great design is simple, powerful, and clean. Use when the user asks to simplify, declutter, reduce noise, remove elements, or make a UI cleaner and more focused."
3
+
description: "Strip designs to their essence by removing unnecessary complexity. Great design is simple, powerful, and clean. Use when user asks to simplify, declutter, reduce noise, remove elements, or make UI cleaner and more focused."
4
4
argument-hint: "[target]"
5
5
user-invocable: true
6
6
---
7
7
8
-
Remove unnecessary complexity from designs, revealing the essential elements and creating clarity through ruthless simplification.
8
+
Remove unnecessary complexity from designs, revealing essential elements and creating clarity through ruthless simplification.
9
9
10
10
## MANDATORY PREPARATION
11
11
12
-
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first.
12
+
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and Context Gathering Protocol. Follow protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first.
13
13
14
14
---
15
15
16
16
## Assess Current State
17
17
18
-
Analyze what makes the design feel complex or cluttered.
18
+
Analyze what makes design feel complex or cluttered.
19
19
20
20
### 1. Identify complexity sources
21
21
- **Too many elements**: Competing buttons, redundant information, visual clutter
···
31
31
- What can be removed, hidden, or combined?
32
32
- What is 20% that delivers 80% of value?
33
33
34
-
If any of these are unclear from the codebase, {{ask_instruction}}
34
+
If any of these are unclear from codebase, {{ask_instruction}}
35
35
36
-
**CRITICAL**: Simplicity is not about removing features. It is about removing obstacles between users and their goals. Every element should justify its existence.
36
+
**CRITICAL**: Simplicity is not about removing features. it's about removing obstacles between users and their goals. Every element should justify its existence.
37
37
38
38
## Plan Simplification
39
39
40
-
Create a ruthless editing strategy.
40
+
Create ruthless editing strategy.
41
41
42
42
- **Core purpose**: What is ONE thing this should accomplish?
43
43
- **Essential elements**: What is truly necessary to achieve that purpose?
···
55
55
- **Progressive disclosure**: Hide complexity behind clear entry points (accordions, modals, step-through flows)
56
56
- **Combine related actions**: Merge similar buttons, consolidate forms, group related content
57
57
- **Clear hierarchy**: ONE primary action, few secondary actions, everything else tertiary or hidden
58
-
- **Remove redundancy**: If it is said elsewhere, do not repeat it here
58
+
- **Remove redundancy**: If it's said elsewhere, do not repeat it here
59
59
60
60
### Visual Simplification
61
61
- **Reduce color palette**: Use 1-2 colors plus neutrals, not 5-7 colors
···
118
118
- Consider if they need alternative access points
119
119
- Note any user feedback to monitor
120
120
121
-
Remember: You have great taste and judgment. Simplification is an act of confidence: knowing what to keep and courage to remove the rest. As Antoine de Saint-Exupery said: "Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away."
121
+
Remember: You have great taste and judgment. Simplification is act of confidence: knowing what to keep and courage to remove rest. As Antoine de Saint-Exupery said: "Perfection is achieved not when there's nothing more to add, but when there's nothing left to take away."
-121
skills/distill/SKILL.md.original.md
-121
skills/distill/SKILL.md.original.md
···
1
-
---
2
-
name: distill
3
-
description: "Strip designs to their essence by removing unnecessary complexity. Great design is simple, powerful, and clean. Use when the user asks to simplify, declutter, reduce noise, remove elements, or make a UI cleaner and more focused."
4
-
argument-hint: "[target]"
5
-
user-invocable: true
6
-
---
7
-
8
-
Remove unnecessary complexity from designs, revealing the essential elements and creating clarity through ruthless simplification.
9
-
10
-
## MANDATORY PREPARATION
11
-
12
-
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first.
13
-
14
-
---
15
-
16
-
## Assess Current State
17
-
18
-
Analyze what makes the design feel complex or cluttered.
19
-
20
-
### 1. Identify complexity sources
21
-
- **Too many elements**: Competing buttons, redundant information, visual clutter
22
-
- **Excessive variation**: Too many colors, fonts, sizes, styles without purpose
23
-
- **Information overload**: Everything visible at once, no progressive disclosure
24
-
- **Visual noise**: Unnecessary borders, shadows, backgrounds, decorations
25
-
- **Confusing hierarchy**: Unclear what matters most
26
-
- **Feature creep**: Too many options, actions, or paths forward
27
-
28
-
### 2. Find the essence
29
-
- What is the primary user goal? (There should be ONE)
30
-
- What is actually necessary vs nice-to-have?
31
-
- What can be removed, hidden, or combined?
32
-
- What is the 20% that delivers 80% of value?
33
-
34
-
If any of these are unclear from the codebase, {{ask_instruction}}
35
-
36
-
**CRITICAL**: Simplicity is not about removing features. It is about removing obstacles between users and their goals. Every element should justify its existence.
37
-
38
-
## Plan Simplification
39
-
40
-
Create a ruthless editing strategy.
41
-
42
-
- **Core purpose**: What is the ONE thing this should accomplish?
43
-
- **Essential elements**: What is truly necessary to achieve that purpose?
44
-
- **Progressive disclosure**: What can be hidden until needed?
45
-
- **Consolidation opportunities**: What can be combined or integrated?
46
-
47
-
**IMPORTANT**: Simplification is hard. It requires saying no to good ideas to make room for great execution. Be ruthless.
48
-
49
-
## Simplify the Design
50
-
51
-
Systematically remove complexity across these dimensions.
52
-
53
-
### Information Architecture
54
-
- **Reduce scope**: Remove secondary actions, optional features, redundant information
55
-
- **Progressive disclosure**: Hide complexity behind clear entry points (accordions, modals, step-through flows)
56
-
- **Combine related actions**: Merge similar buttons, consolidate forms, group related content
57
-
- **Clear hierarchy**: ONE primary action, few secondary actions, everything else tertiary or hidden
58
-
- **Remove redundancy**: If it is said elsewhere, do not repeat it here
59
-
60
-
### Visual Simplification
61
-
- **Reduce color palette**: Use 1-2 colors plus neutrals, not 5-7 colors
62
-
- **Limit typography**: One font family, 3-4 sizes maximum, 2-3 weights
63
-
- **Remove decorations**: Eliminate borders, shadows, backgrounds that do not serve hierarchy or function
64
-
- **Flatten structure**: Reduce nesting, remove unnecessary containers. Never nest cards inside cards.
65
-
- **Remove unnecessary cards**: Cards are not needed for basic layout. Use spacing and alignment instead.
66
-
- **Consistent spacing**: Use one spacing scale, remove arbitrary gaps
67
-
68
-
### Layout Simplification
69
-
- **Linear flow**: Replace complex grids with simple vertical flow where possible
70
-
- **Remove sidebars**: Move secondary content inline or hide it
71
-
- **Full-width**: Use available space generously instead of complex multi-column layouts
72
-
- **Consistent alignment**: Pick left or center, stick with it
73
-
- **Generous white space**: Let content breathe, do not pack everything tight
74
-
75
-
### Interaction Simplification
76
-
- **Reduce choices**: Fewer buttons, fewer options, clearer path forward (paradox of choice is real)
77
-
- **Smart defaults**: Make common choices automatic, only ask when necessary
78
-
- **Inline actions**: Replace modal flows with inline editing where possible
79
-
- **Remove steps**: Can signup be one step instead of three? Can checkout be simplified?
80
-
- **Clear CTAs**: ONE obvious next step, not five competing actions
81
-
82
-
### Content Simplification
83
-
- **Shorter copy**: Cut every sentence in half, then do it again
84
-
- **Active voice**: "Save changes" not "Changes will be saved"
85
-
- **Remove jargon**: Plain language always wins
86
-
- **Scannable structure**: Short paragraphs, bullet points, clear headings
87
-
- **Essential information only**: Remove marketing fluff, legalese, hedging
88
-
- **Remove redundant copy**: No headers restating intros, no repeated explanations, say it once
89
-
90
-
### Code Simplification
91
-
- **Remove unused code**: Dead CSS, unused components, orphaned files
92
-
- **Flatten component trees**: Reduce nesting depth
93
-
- **Consolidate styles**: Merge similar styles, use utilities consistently
94
-
- **Reduce variants**: Does that component need 12 variations, or can 3 cover 90% of cases?
95
-
96
-
**NEVER**:
97
-
- Remove necessary functionality (simplicity equals feature-less)
98
-
- Sacrifice accessibility for simplicity (clear labels and ARIA still required)
99
-
- Make things so simple they are unclear (mystery equals minimalism)
100
-
- Remove information users need to make decisions
101
-
- Eliminate hierarchy completely (some things should stand out)
102
-
- Oversimplify complex domains (match complexity to actual task complexity)
103
-
104
-
## Verify Simplification
105
-
106
-
Ensure simplification improves usability.
107
-
108
-
- **Faster task completion**: Can users accomplish goals more quickly?
109
-
- **Reduced cognitive load**: Is it easier to understand what to do?
110
-
- **Still complete**: Are all necessary features still accessible?
111
-
- **Clearer hierarchy**: Is it obvious what matters most?
112
-
- **Better performance**: Does simpler design load faster?
113
-
114
-
## Document Removed Complexity
115
-
116
-
If you removed features or options:
117
-
- Document why they were removed
118
-
- Consider if they need alternative access points
119
-
- Note any user feedback to monitor
120
-
121
-
Remember: You have great taste and judgment. Simplification is an act of confidence: knowing what to keep and courage to remove the rest. As Antoine de Saint-Exupery said: "Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away."
+7
-7
skills/extract/SKILL.md
+7
-7
skills/extract/SKILL.md
···
1
1
---
2
2
name: extract
3
-
description: "Extract and consolidate reusable components, design tokens, and patterns into your design system. Identifies opportunities for systematic reuse and enriches your component library. Use when the user asks to create components, refactor repeated UI patterns, build a design system, or extract tokens."
3
+
description: "Extract and consolidate reusable components, design tokens, and patterns into your design system. Identifies opportunities for systematic reuse and enriches your component library. Use when user asks to create components, refactor repeated UI patterns, build design system, or extract tokens."
4
4
argument-hint: "[target]"
5
5
user-invocable: true
6
6
---
7
7
8
-
Identify reusable patterns, components, and design tokens, then extract and consolidate them into the design system for systematic reuse.
8
+
Identify reusable patterns, components, and design tokens, then extract and consolidate them into design system for systematic reuse.
9
9
10
10
## Discover
11
11
12
-
Analyze the target area to identify extraction opportunities.
12
+
Analyze target area to identify extraction opportunities.
13
13
14
14
### 1. Find the design system
15
15
Locate your design system, component library, or shared UI directory (grep for "design system", "ui", "components", etc.). Understand its structure:
···
18
18
- Documentation patterns
19
19
- Import and export conventions
20
20
21
-
**CRITICAL**: If no design system exists, ask before creating one. Understand the preferred location and structure first.
21
+
**CRITICAL**: If no design system exists, ask before creating one. Understand preferred location and structure first.
22
22
23
23
### 2. Identify patterns
24
24
Look for:
···
36
36
37
37
## Plan Extraction
38
38
39
-
Create a systematic extraction plan.
39
+
Create systematic extraction plan.
40
40
41
41
- **Components to extract**: Which UI elements become reusable components?
42
42
- **Tokens to create**: Which hard-coded values become design tokens?
···
75
75
76
76
## Migrate
77
77
78
-
Replace existing uses with the new shared versions.
78
+
Replace existing uses with new shared versions.
79
79
80
80
- **Find all instances**: Search for patterns you have extracted
81
81
- **Replace systematically**: Update each use consume shared version
···
91
91
- Add examples and guidelines
92
92
- Update any Storybook or component catalog
93
93
94
-
Remember: A good design system is a living system. Extract patterns as they emerge, enrich them thoughtfully, and maintain them consistently.
94
+
Remember: good design system is living system. Extract patterns as they emerge, enrich them thoughtfully, and maintain them consistently.
-94
skills/extract/SKILL.md.original.md
-94
skills/extract/SKILL.md.original.md
···
1
-
---
2
-
name: extract
3
-
description: "Extract and consolidate reusable components, design tokens, and patterns into your design system. Identifies opportunities for systematic reuse and enriches your component library. Use when the user asks to create components, refactor repeated UI patterns, build a design system, or extract tokens."
4
-
argument-hint: "[target]"
5
-
user-invocable: true
6
-
---
7
-
8
-
Identify reusable patterns, components, and design tokens, then extract and consolidate them into the design system for systematic reuse.
9
-
10
-
## Discover
11
-
12
-
Analyze the target area to identify extraction opportunities.
13
-
14
-
### 1. Find the design system
15
-
Locate your design system, component library, or shared UI directory (grep for "design system", "ui", "components", etc.). Understand its structure:
16
-
- Component organization and naming conventions
17
-
- Design token structure (if any)
18
-
- Documentation patterns
19
-
- Import and export conventions
20
-
21
-
**CRITICAL**: If no design system exists, ask before creating one. Understand the preferred location and structure first.
22
-
23
-
### 2. Identify patterns
24
-
Look for:
25
-
- **Repeated components**: Similar UI patterns used multiple times (buttons, cards, inputs, etc.)
26
-
- **Hard-coded values**: Colors, spacing, typography, shadows that should be tokens
27
-
- **Inconsistent variations**: Multiple implementations of the same concept (3 different button styles)
28
-
- **Reusable patterns**: Layout patterns, composition patterns, interaction patterns worth systematizing
29
-
30
-
### 3. Assess value
31
-
Not everything should be extracted. Consider:
32
-
- Is this used 3+ times, or likely to be reused?
33
-
- Would systematizing this improve consistency?
34
-
- Is this a general pattern or context-specific?
35
-
- What is the maintenance cost vs benefit?
36
-
37
-
## Plan Extraction
38
-
39
-
Create a systematic extraction plan.
40
-
41
-
- **Components to extract**: Which UI elements become reusable components?
42
-
- **Tokens to create**: Which hard-coded values become design tokens?
43
-
- **Variants to support**: What variations does each component need?
44
-
- **Naming conventions**: Component names, token names, prop names that match existing patterns
45
-
- **Migration path**: How to refactor existing uses to consume the new shared versions
46
-
47
-
**IMPORTANT**: Design systems grow incrementally. Extract what is clearly reusable now, not everything that might someday be reusable.
48
-
49
-
## Extract and Enrich
50
-
51
-
Build improved, reusable versions.
52
-
53
-
- **Components**: Create well-designed components with:
54
-
- Clear props API with sensible defaults
55
-
- Proper variants for different use cases
56
-
- Accessibility built in (ARIA, keyboard navigation, focus management)
57
-
- Documentation and usage examples
58
-
59
-
- **Design tokens**: Create tokens with:
60
-
- Clear naming (primitive vs semantic)
61
-
- Proper hierarchy and organization
62
-
- Documentation of when to use each token
63
-
64
-
- **Patterns**: Document patterns with:
65
-
- When to use this pattern
66
-
- Code examples
67
-
- Variations and combinations
68
-
69
-
**NEVER**:
70
-
- Extract one-off, context-specific implementations without generalization
71
-
- Create components so generic they are useless
72
-
- Extract without considering existing design system conventions
73
-
- Skip proper TypeScript types or prop documentation
74
-
- Create tokens for every single value (tokens should have semantic meaning)
75
-
76
-
## Migrate
77
-
78
-
Replace existing uses with the new shared versions.
79
-
80
-
- **Find all instances**: Search for the patterns you have extracted
81
-
- **Replace systematically**: Update each use to consume the shared version
82
-
- **Test thoroughly**: Ensure visual and functional parity
83
-
- **Delete dead code**: Remove the old implementations
84
-
85
-
## Document
86
-
87
-
Update design system documentation.
88
-
89
-
- Add new components to the component library
90
-
- Document token usage and values
91
-
- Add examples and guidelines
92
-
- Update any Storybook or component catalog
93
-
94
-
Remember: A good design system is a living system. Extract patterns as they emerge, enrich them thoughtfully, and maintain them consistently.
+21
-21
skills/find-skills/SKILL.md
+21
-21
skills/find-skills/SKILL.md
···
1
1
---
2
2
name: find-skills
3
-
description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
3
+
description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find skill for X", "is there skill that can...", or express interest in extending capabilities. This skill should be used when user is looking for functionality that might exist as installable skill.
4
4
---
5
5
6
6
# Find Skills
7
7
8
-
This skill helps you discover and install skills from the open agent skills ecosystem.
8
+
This skill helps you discover and install skills from open agent skills ecosystem.
9
9
10
10
## When to Use This Skill
11
11
12
-
Use this skill when the user:
12
+
Use this skill when user:
13
13
14
14
- Asks "how do I do X" where X might be common task with existing skill
15
15
- Says "find skill for X" or "is there skill for X"
···
20
20
21
21
## What is the Skills CLI?
22
22
23
-
The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
23
+
Skills CLI (`npx skills`) is package manager for open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
24
24
25
25
**Key commands:**
26
26
···
35
35
36
36
### Step 1: Understand What They Need
37
37
38
-
When a user asks for help with something, identify:
38
+
When user asks for help with something, identify:
39
39
40
-
1. The domain (e.g., React, testing, design, deployment)
41
-
2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
42
-
3. Whether this is a common enough task that a skill likely exists
40
+
1. domain (e.g., React, testing, design, deployment)
41
+
2. specific task (e.g., writing tests, creating animations, reviewing PRs)
42
+
3. Whether this is common enough task that skill likely exists
43
43
44
44
### Step 2: Check the Leaderboard First
45
45
46
-
Before running a CLI search, check the [skills.sh leaderboard](https://skills.sh/) to see if a well-known skill already exists for the domain. The leaderboard ranks skills by total installs, surfacing the most popular and battle-tested options.
46
+
Before running CLI search, check [skills.sh leaderboard](https://skills.sh/) to see if well-known skill already exists for domain. leaderboard ranks skills by total installs, surfacing most popular and battle-tested options.
47
47
48
48
For example, top skills for web development include:
49
49
- `vercel-labs/agent-skills` — React, Next.js, web design (100K+ installs each)
···
51
51
52
52
### Step 3: Search for Skills
53
53
54
-
If the leaderboard doesn't cover the user's need, run the find command:
54
+
If leaderboard doesn't cover user's need, run find command:
55
55
56
56
```bash
57
57
npx skills find [query]
···
65
65
66
66
### Step 4: Verify Quality Before Recommending
67
67
68
-
**Do not recommend a skill based solely on search results.** Always verify:
68
+
**Do not recommend skill based solely on search results.** Always verify:
69
69
70
70
1. **Install count** — Prefer skills with 1K+ installs. Be cautious with anything under 100.
71
71
2. **Source reputation** — Official sources (`vercel-labs`, `anthropics`, `microsoft`) are more trustworthy than unknown authors.
72
-
3. **GitHub stars** — Check the source repository. A skill from a repo with <100 stars should be treated with skepticism.
72
+
3. **GitHub stars** — Check source repository. skill from repo with <100 stars should be treated with skepticism.
73
73
74
74
### Step 5: Present Options to the User
75
75
76
-
When you find relevant skills, present them to the user with:
76
+
When you find relevant skills, present them to user with:
77
77
78
-
1. The skill name and what it does
79
-
2. The install count and source
80
-
3. The install command they can run
81
-
4. A link to learn more at skills.sh
78
+
1. skill name and what it does
79
+
2. install count and source
80
+
3. install command they can run
81
+
4. link to learn more at skills.sh
82
82
83
83
Example response:
84
84
···
95
95
96
96
### Step 6: Offer to Install
97
97
98
-
If the user wants to proceed, you can install the skill for them:
98
+
If user wants to proceed, install skill for them:
99
99
100
100
```bash
101
101
npx skills add <owner/repo@skill> -g -y
102
102
```
103
103
104
-
The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
104
+
`-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
105
105
106
106
## Common Skill Categories
107
107
···
128
128
If no relevant skills exist:
129
129
130
130
1. Acknowledge that no existing skill was found
131
-
2. Offer to help with the task directly using your general capabilities
132
-
3. Suggest the user could create their own skill with `npx skills init`
131
+
2. Offer to help with task directly using your general capabilities
132
+
3. Suggest user could create their own skill with `npx skills init`
133
133
134
134
Example:
135
135
-142
skills/find-skills/SKILL.md.original.md
-142
skills/find-skills/SKILL.md.original.md
···
1
-
---
2
-
name: find-skills
3
-
description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
4
-
---
5
-
6
-
# Find Skills
7
-
8
-
This skill helps you discover and install skills from the open agent skills ecosystem.
9
-
10
-
## When to Use This Skill
11
-
12
-
Use this skill when the user:
13
-
14
-
- Asks "how do I do X" where X might be a common task with an existing skill
15
-
- Says "find a skill for X" or "is there a skill for X"
16
-
- Asks "can you do X" where X is a specialized capability
17
-
- Expresses interest in extending agent capabilities
18
-
- Wants to search for tools, templates, or workflows
19
-
- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
20
-
21
-
## What is the Skills CLI?
22
-
23
-
The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
24
-
25
-
**Key commands:**
26
-
27
-
- `npx skills find [query]` - Search for skills interactively or by keyword
28
-
- `npx skills add <package>` - Install a skill from GitHub or other sources
29
-
- `npx skills check` - Check for skill updates
30
-
- `npx skills update` - Update all installed skills
31
-
32
-
**Browse skills at:** https://skills.sh/
33
-
34
-
## How to Help Users Find Skills
35
-
36
-
### Step 1: Understand What They Need
37
-
38
-
When a user asks for help with something, identify:
39
-
40
-
1. The domain (e.g., React, testing, design, deployment)
41
-
2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
42
-
3. Whether this is a common enough task that a skill likely exists
43
-
44
-
### Step 2: Check the Leaderboard First
45
-
46
-
Before running a CLI search, check the [skills.sh leaderboard](https://skills.sh/) to see if a well-known skill already exists for the domain. The leaderboard ranks skills by total installs, surfacing the most popular and battle-tested options.
47
-
48
-
For example, top skills for web development include:
49
-
- `vercel-labs/agent-skills` — React, Next.js, web design (100K+ installs each)
50
-
- `anthropics/skills` — Frontend design, document processing (100K+ installs)
51
-
52
-
### Step 3: Search for Skills
53
-
54
-
If the leaderboard doesn't cover the user's need, run the find command:
55
-
56
-
```bash
57
-
npx skills find [query]
58
-
```
59
-
60
-
For example:
61
-
62
-
- User asks "how do I make my React app faster?" → `npx skills find react performance`
63
-
- User asks "can you help me with PR reviews?" → `npx skills find pr review`
64
-
- User asks "I need to create a changelog" → `npx skills find changelog`
65
-
66
-
### Step 4: Verify Quality Before Recommending
67
-
68
-
**Do not recommend a skill based solely on search results.** Always verify:
69
-
70
-
1. **Install count** — Prefer skills with 1K+ installs. Be cautious with anything under 100.
71
-
2. **Source reputation** — Official sources (`vercel-labs`, `anthropics`, `microsoft`) are more trustworthy than unknown authors.
72
-
3. **GitHub stars** — Check the source repository. A skill from a repo with <100 stars should be treated with skepticism.
73
-
74
-
### Step 5: Present Options to the User
75
-
76
-
When you find relevant skills, present them to the user with:
77
-
78
-
1. The skill name and what it does
79
-
2. The install count and source
80
-
3. The install command they can run
81
-
4. A link to learn more at skills.sh
82
-
83
-
Example response:
84
-
85
-
```
86
-
I found a skill that might help! The "react-best-practices" skill provides
87
-
React and Next.js performance optimization guidelines from Vercel Engineering.
88
-
(185K installs)
89
-
90
-
To install it:
91
-
npx skills add vercel-labs/agent-skills@react-best-practices
92
-
93
-
Learn more: https://skills.sh/vercel-labs/agent-skills/react-best-practices
94
-
```
95
-
96
-
### Step 6: Offer to Install
97
-
98
-
If the user wants to proceed, you can install the skill for them:
99
-
100
-
```bash
101
-
npx skills add <owner/repo@skill> -g -y
102
-
```
103
-
104
-
The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
105
-
106
-
## Common Skill Categories
107
-
108
-
When searching, consider these common categories:
109
-
110
-
| Category | Example Queries |
111
-
| --------------- | ---------------------------------------- |
112
-
| Web Development | react, nextjs, typescript, css, tailwind |
113
-
| Testing | testing, jest, playwright, e2e |
114
-
| DevOps | deploy, docker, kubernetes, ci-cd |
115
-
| Documentation | docs, readme, changelog, api-docs |
116
-
| Code Quality | review, lint, refactor, best-practices |
117
-
| Design | ui, ux, design-system, accessibility |
118
-
| Productivity | workflow, automation, git |
119
-
120
-
## Tips for Effective Searches
121
-
122
-
1. **Use specific keywords**: "react testing" is better than just "testing"
123
-
2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
124
-
3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
125
-
126
-
## When No Skills Are Found
127
-
128
-
If no relevant skills exist:
129
-
130
-
1. Acknowledge that no existing skill was found
131
-
2. Offer to help with the task directly using your general capabilities
132
-
3. Suggest the user could create their own skill with `npx skills init`
133
-
134
-
Example:
135
-
136
-
```
137
-
I searched for skills related to "xyz" but didn't find any matches.
138
-
I can still help you with this task directly! Would you like me to proceed?
139
-
140
-
If this is something you do often, you could create your own skill:
141
-
npx skills init my-xyz-skill
142
-
```
+34
-34
skills/frontend-design/SKILL.md
+34
-34
skills/frontend-design/SKILL.md
···
1
1
---
2
2
name: frontend-design
3
-
description: "Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context."
3
+
description: "Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context."
4
4
license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution.
5
5
---
6
6
···
15
15
- **Use cases**: What jobs are they trying to get done?
16
16
- **Brand personality or tone**: How should interface feel?
17
17
18
-
Individual skills may require additional context. Check the skill preparation section for specifics.
18
+
Individual skills may require additional context. Check skill preparation section for specifics.
19
19
20
-
**CRITICAL**: You cannot infer this context by reading the codebase. Code tells you what was built, not who it is for or what it should feel like. Only the creator can provide this context.
20
+
**CRITICAL**: You cannot infer this context by reading codebase. Code tells you what was built, not who it's for or what it should feel like. Only creator can provide this context.
21
21
22
22
**Gathering order:**
23
-
1. **Check current instructions (instant)**: If your loaded instructions already contains a Design Context section, proceed immediately.
24
-
2. **Check.impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed.
25
-
3. **Run teach-impeccable (REQUIRED)**: If neither source has context, you MUST run {{command_prefix}}teach-impeccable NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead.
23
+
1. **Check current instructions (instant)**: If your loaded instructions already contains Design Context section, proceed immediately.
24
+
2. **Check.impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from project root. If it exists and contains required context, proceed.
25
+
3. **Run teach-impeccable (REQUIRED)**: If neither source has context, you MUST run {{command_prefix}}teach-impeccable NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from codebase instead.
26
26
27
27
---
28
28
29
29
## Design Direction
30
30
31
-
Commit to a BOLD aesthetic direction:
31
+
Commit to BOLD aesthetic direction:
32
32
- **Purpose**: What problem does this interface solve? Who uses it?
33
-
- **Tone**: Pick extreme: brutally minimal, maximalist chaos, retro-futuristic, organic or natural, luxury or refined, playful or toy-like, editorial or magazine, brutalist or raw, art deco or geometric, soft or pastel, industrial or utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to aesthetic direction.
33
+
- **Tone**: Pick extreme: brutally minimal, maximalist chaos, retro-futuristic, organic or natural, luxury or refined, playful or toy-like, editorial or magazine, brutalist or raw, art deco or geometric, soft or pastel, industrial or utilitarian, etc. there're so many flavors to choose from. Use these for inspiration but design one that is true to aesthetic direction.
34
34
- **Constraints**: Technical requirements (framework, performance, accessibility).
35
35
- **Differentiation**: What makes this UNFORGETTABLE? What is one thing someone will remember?
36
36
37
-
**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work. The key is intentionality, not intensity.
37
+
**CRITICAL**: Choose clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work. key is intentionality, not intensity.
38
38
39
39
Then implement working code that is:
40
40
- Production-grade and functional
···
47
47
### Typography
48
48
> *Consult [typography reference](reference/typography.md) for scales, pairing, and loading strategies.*
49
49
50
-
Choose fonts that are beautiful, unique, and interesting. Pair a distinctive display font with a refined body font.
50
+
Choose fonts that are beautiful, unique, and interesting. Pair distinctive display font with refined body font.
51
51
52
-
**DO**: Use a modular type scale with fluid sizing (clamp)
52
+
**DO**: Use modular type scale with fluid sizing (clamp)
53
53
**DO**: Vary font weights and sizes to create clear visual hierarchy
54
54
**DON'T**: Use overused fonts: Inter, Roboto, Arial, Open Sans, system defaults
55
55
**DON'T**: Use monospace typography as lazy shorthand for "technical or developer" vibes
···
58
58
### Color and Theme
59
59
> *Consult [color reference](reference/color-and-contrast.md) for OKLCH, palettes, and dark mode.*
60
60
61
-
Commit to a cohesive palette. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
61
+
Commit to cohesive palette. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
62
62
63
63
**DO**: Use modern CSS color functions (oklch, color-mix, light-dark) for perceptually uniform, maintainable palettes
64
-
**DO**: Tint your neutrals toward your brand hue. Even a subtle hint creates subconscious cohesion
65
-
**DON'T**: Use gray text on colored backgrounds. It looks washed out. Use a shade of the background color instead.
64
+
**DO**: Tint your neutrals toward your brand hue. Even subtle hint creates subconscious cohesion
65
+
**DON'T**: Use gray text on colored backgrounds. It looks washed out. Use shade of background color instead.
66
66
**DON'T**: Use pure black (#000) or pure white (#fff). Always tint. Pure black or white never appears in nature.
67
-
**DON'T**: Use the AI color palette: cyan on dark, purple to blue gradients, neon accents on dark backgrounds
68
-
**DON'T**: Use gradient text for "impact". Especially on metrics or headings. It is decorative rather than meaningful.
67
+
**DON'T**: Use AI color palette: cyan on dark, purple to blue gradients, neon accents on dark backgrounds
68
+
**DON'T**: Use gradient text for "impact". Especially on metrics or headings. it's decorative rather than meaningful.
69
69
**DON'T**: Default to dark mode with glowing accents. It looks "cool" without requiring actual design decisions.
70
70
71
71
### Layout and Space
72
72
> *Consult [spatial reference](reference/spatial-design.md) for grids, rhythm, and container queries.*
73
73
74
-
Create visual rhythm through varied spacing. Not the same padding everywhere. Embrace asymmetry and unexpected compositions. Break the grid intentionally for emphasis.
74
+
Create visual rhythm through varied spacing. Not same padding everywhere. Embrace asymmetry and unexpected compositions. Break grid intentionally for emphasis.
75
75
76
76
**DO**: Create visual rhythm through varied spacing: tight groupings, generous separations
77
77
**DO**: Use fluid spacing with clamp() that breathes on larger screens
78
-
**DO**: Use asymmetry and unexpected compositions. Break the grid intentionally for emphasis.
79
-
**DON'T**: Wrap everything in cards. Not everything needs a container.
80
-
**DON'T**: Nest cards inside cards. Visual noise. Flatten the hierarchy.
78
+
**DO**: Use asymmetry and unexpected compositions. Break grid intentionally for emphasis.
79
+
**DON'T**: Wrap everything in cards. Not everything needs container.
80
+
**DON'T**: Nest cards inside cards. Visual noise. Flatten hierarchy.
81
81
**DON'T**: Use identical card grids. Same-sized cards with icon, heading, text, repeated endlessly.
82
-
**DON'T**: Use the hero metric layout template. Big number, small label, supporting stats, gradient accent.
82
+
**DON'T**: Use hero metric layout template. Big number, small label, supporting stats, gradient accent.
83
83
**DON'T**: Center everything. Left-aligned text with asymmetric layouts feels more designed.
84
-
**DON'T**: Use the same spacing everywhere. Without rhythm, layouts feel monotonous.
84
+
**DON'T**: Use same spacing everywhere. Without rhythm, layouts feel monotonous.
85
85
86
86
### Visual Details
87
87
**DO**: Use intentional, purposeful decorative elements that reinforce brand.
88
88
**DON'T**: Use glassmorphism everywhere. Blur effects, glass cards, glow borders used decoratively rather than purposefully.
89
-
**DON'T**: Use rounded elements with thick colored border on one side. A lazy accent that almost never looks intentional.
89
+
**DON'T**: Use rounded elements with thick colored border on one side. lazy accent that almost never looks intentional.
90
90
**DON'T**: Use sparklines as decoration. Tiny charts that look sophisticated but convey nothing meaningful.
91
91
**DON'T**: Use rounded rectangles with generic drop shadows. Safe, forgettable, could be any AI output.
92
-
**DON'T**: Use modals unless there is truly no better alternative. Modals are lazy.
92
+
**DON'T**: Use modals unless there's truly no better alternative. Modals are lazy.
93
93
94
94
### Motion
95
95
> *Consult [motion reference](reference/motion-design.md) for timing, easing, and reduced motion.*
···
108
108
Make interactions feel fast. Use optimistic UI: update immediately, sync later.
109
109
110
110
**DO**: Use progressive disclosure. Start simple, reveal sophistication through interaction (basic options first, advanced behind expandable sections; hover states that reveal secondary actions).
111
-
**DO**: Design empty states that teach the interface, not say "nothing here"
111
+
**DO**: Design empty states that teach interface, not say "nothing here"
112
112
**DO**: Make every interactive surface feel intentional and responsive.
113
-
**DON'T**: Repeat the same information. Redundant headers, intros that restate the heading.
113
+
**DON'T**: Repeat same information. Redundant headers, intros that restate heading.
114
114
**DON'T**: Make every button primary. Use ghost buttons, text links, secondary styles. Hierarchy matters.
115
115
116
116
### Responsive
117
117
> *Consult [responsive reference](reference/responsive-design.md) for mobile-first, fluid design, and container queries.*
118
118
119
119
**DO**: Use container queries (@container) for component-level responsiveness
120
-
**DO**: Adapt the interface for different contexts. Do not shrink it.
121
-
**DON'T**: Hide critical functionality on mobile. Adapt the interface, do not amputate it.
120
+
**DO**: Adapt interface for different contexts. Do not shrink it.
121
+
**DON'T**: Hide critical functionality on mobile. Adapt interface, do not amputate it.
122
122
123
123
### UX Writing
124
124
> *Consult [ux-writing reference](reference/ux-writing.md) for labels, errors, and empty states.*
···
130
130
131
131
## The AI Slop Test
132
132
133
-
**Critical quality check**: If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that is the problem.
133
+
**Critical quality check**: If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that is problem.
134
134
135
-
A distinctive interface should make someone ask "how was this made?" not "which AI made this?"
135
+
distinctive interface should make someone ask "how was this made?" not "which AI made this?"
136
136
137
-
Review the DO NOT guidelines above. They are the fingerprints of AI-generated work from 2024-2025.
137
+
Review DO NOT guidelines above. They are fingerprints of AI-generated work from 2024-2025.
138
138
139
139
---
140
140
141
141
## Implementation Principles
142
142
143
-
Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details.
143
+
Match implementation complexity to aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details.
144
144
145
-
Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices across generations.
145
+
Interpret creatively and make unexpected choices that feel genuinely designed for context. No design should be same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices across generations.
146
146
147
-
Remember: {{model}} is capable of extraordinary creative work. Do not hold back. Show what can truly be created when thinking outside the box and committing fully to a distinctive vision.
147
+
Remember: {{model}} is capable of extraordinary creative work. Do not hold back. Show what can truly be created when thinking outside box and committing fully to distinctive vision.
-147
skills/frontend-design/SKILL.md.original.md
-147
skills/frontend-design/SKILL.md.original.md
···
1
-
---
2
-
name: frontend-design
3
-
description: "Create distinctive, production-grade frontend interfaces with high design quality. Generates creative, polished code that avoids generic AI aesthetics. Use when the user asks to build web components, pages, artifacts, posters, or applications, or when any design skill requires project context."
4
-
license: Apache 2.0. Based on Anthropic's frontend-design skill. See NOTICE.md for attribution.
5
-
---
6
-
7
-
This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
8
-
9
-
## Context Gathering Protocol
10
-
11
-
Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work.
12
-
13
-
**Required context** — every design skill needs at minimum:
14
-
- **Target audience**: Who uses this product and in what context?
15
-
- **Use cases**: What jobs are they trying to get done?
16
-
- **Brand personality or tone**: How should the interface feel?
17
-
18
-
Individual skills may require additional context. Check the skill preparation section for specifics.
19
-
20
-
**CRITICAL**: You cannot infer this context by reading the codebase. Code tells you what was built, not who it is for or what it should feel like. Only the creator can provide this context.
21
-
22
-
**Gathering order:**
23
-
1. **Check current instructions (instant)**: If your loaded instructions already contains a Design Context section, proceed immediately.
24
-
2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed.
25
-
3. **Run teach-impeccable (REQUIRED)**: If neither source has context, you MUST run {{command_prefix}}teach-impeccable NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead.
26
-
27
-
---
28
-
29
-
## Design Direction
30
-
31
-
Commit to a BOLD aesthetic direction:
32
-
- **Purpose**: What problem does this interface solve? Who uses it?
33
-
- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic or natural, luxury or refined, playful or toy-like, editorial or magazine, brutalist or raw, art deco or geometric, soft or pastel, industrial or utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
34
-
- **Constraints**: Technical requirements (framework, performance, accessibility).
35
-
- **Differentiation**: What makes this UNFORGETTABLE? What is the one thing someone will remember?
36
-
37
-
**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work. The key is intentionality, not intensity.
38
-
39
-
Then implement working code that is:
40
-
- Production-grade and functional
41
-
- Visually striking and memorable
42
-
- Cohesive with a clear aesthetic point of view
43
-
- Meticulously refined in every detail
44
-
45
-
## Frontend Aesthetics Guidelines
46
-
47
-
### Typography
48
-
> *Consult [typography reference](reference/typography.md) for scales, pairing, and loading strategies.*
49
-
50
-
Choose fonts that are beautiful, unique, and interesting. Pair a distinctive display font with a refined body font.
51
-
52
-
**DO**: Use a modular type scale with fluid sizing (clamp)
53
-
**DO**: Vary font weights and sizes to create clear visual hierarchy
54
-
**DON'T**: Use overused fonts: Inter, Roboto, Arial, Open Sans, system defaults
55
-
**DON'T**: Use monospace typography as lazy shorthand for "technical or developer" vibes
56
-
**DON'T**: Put large icons with rounded corners above every heading. They rarely add value and make sites look templated
57
-
58
-
### Color and Theme
59
-
> *Consult [color reference](reference/color-and-contrast.md) for OKLCH, palettes, and dark mode.*
60
-
61
-
Commit to a cohesive palette. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
62
-
63
-
**DO**: Use modern CSS color functions (oklch, color-mix, light-dark) for perceptually uniform, maintainable palettes
64
-
**DO**: Tint your neutrals toward your brand hue. Even a subtle hint creates subconscious cohesion
65
-
**DON'T**: Use gray text on colored backgrounds. It looks washed out. Use a shade of the background color instead.
66
-
**DON'T**: Use pure black (#000) or pure white (#fff). Always tint. Pure black or white never appears in nature.
67
-
**DON'T**: Use the AI color palette: cyan on dark, purple to blue gradients, neon accents on dark backgrounds
68
-
**DON'T**: Use gradient text for "impact". Especially on metrics or headings. It is decorative rather than meaningful.
69
-
**DON'T**: Default to dark mode with glowing accents. It looks "cool" without requiring actual design decisions.
70
-
71
-
### Layout and Space
72
-
> *Consult [spatial reference](reference/spatial-design.md) for grids, rhythm, and container queries.*
73
-
74
-
Create visual rhythm through varied spacing. Not the same padding everywhere. Embrace asymmetry and unexpected compositions. Break the grid intentionally for emphasis.
75
-
76
-
**DO**: Create visual rhythm through varied spacing: tight groupings, generous separations
77
-
**DO**: Use fluid spacing with clamp() that breathes on larger screens
78
-
**DO**: Use asymmetry and unexpected compositions. Break the grid intentionally for emphasis.
79
-
**DON'T**: Wrap everything in cards. Not everything needs a container.
80
-
**DON'T**: Nest cards inside cards. Visual noise. Flatten the hierarchy.
81
-
**DON'T**: Use identical card grids. Same-sized cards with icon, heading, text, repeated endlessly.
82
-
**DON'T**: Use the hero metric layout template. Big number, small label, supporting stats, gradient accent.
83
-
**DON'T**: Center everything. Left-aligned text with asymmetric layouts feels more designed.
84
-
**DON'T**: Use the same spacing everywhere. Without rhythm, layouts feel monotonous.
85
-
86
-
### Visual Details
87
-
**DO**: Use intentional, purposeful decorative elements that reinforce brand.
88
-
**DON'T**: Use glassmorphism everywhere. Blur effects, glass cards, glow borders used decoratively rather than purposefully.
89
-
**DON'T**: Use rounded elements with thick colored border on one side. A lazy accent that almost never looks intentional.
90
-
**DON'T**: Use sparklines as decoration. Tiny charts that look sophisticated but convey nothing meaningful.
91
-
**DON'T**: Use rounded rectangles with generic drop shadows. Safe, forgettable, could be any AI output.
92
-
**DON'T**: Use modals unless there is truly no better alternative. Modals are lazy.
93
-
94
-
### Motion
95
-
> *Consult [motion reference](reference/motion-design.md) for timing, easing, and reduced motion.*
96
-
97
-
Focus on high-impact moments. One well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions.
98
-
99
-
**DO**: Use motion to convey state changes: entrances, exits, feedback
100
-
**DO**: Use exponential easing (ease-out-quart, quint, or expo) for natural deceleration
101
-
**DO**: For height animations, use grid-template-rows transitions instead of animating height directly.
102
-
**DON'T**: Animate layout properties (width, height, padding, margin). Use transform and opacity only.
103
-
**DON'T**: Use bounce or elastic easing. They feel dated and tacky. Real objects decelerate smoothly.
104
-
105
-
### Interaction
106
-
> *Consult [interaction reference](reference/interaction-design.md) for forms, focus, and loading patterns.*
107
-
108
-
Make interactions feel fast. Use optimistic UI: update immediately, sync later.
109
-
110
-
**DO**: Use progressive disclosure. Start simple, reveal sophistication through interaction (basic options first, advanced behind expandable sections; hover states that reveal secondary actions).
111
-
**DO**: Design empty states that teach the interface, not just say "nothing here"
112
-
**DO**: Make every interactive surface feel intentional and responsive.
113
-
**DON'T**: Repeat the same information. Redundant headers, intros that restate the heading.
114
-
**DON'T**: Make every button primary. Use ghost buttons, text links, secondary styles. Hierarchy matters.
115
-
116
-
### Responsive
117
-
> *Consult [responsive reference](reference/responsive-design.md) for mobile-first, fluid design, and container queries.*
118
-
119
-
**DO**: Use container queries (@container) for component-level responsiveness
120
-
**DO**: Adapt the interface for different contexts. Do not just shrink it.
121
-
**DON'T**: Hide critical functionality on mobile. Adapt the interface, do not amputate it.
122
-
123
-
### UX Writing
124
-
> *Consult [ux-writing reference](reference/ux-writing.md) for labels, errors, and empty states.*
125
-
126
-
**DO**: Make every word earn its place.
127
-
**DON'T**: Repeat information users can already see.
128
-
129
-
---
130
-
131
-
## The AI Slop Test
132
-
133
-
**Critical quality check**: If you showed this interface to someone and said "AI made this," would they believe you immediately? If yes, that is the problem.
134
-
135
-
A distinctive interface should make someone ask "how was this made?" not "which AI made this?"
136
-
137
-
Review the DO NOT guidelines above. They are the fingerprints of AI-generated work from 2024-2025.
138
-
139
-
---
140
-
141
-
## Implementation Principles
142
-
143
-
Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details.
144
-
145
-
Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices across generations.
146
-
147
-
Remember: {{model}} is capable of extraordinary creative work. Do not hold back. Show what can truly be created when thinking outside the box and committing fully to a distinctive vision.
+2
-2
skills/harden/SKILL.md
+2
-2
skills/harden/SKILL.md
···
1
1
---
2
2
name: harden
3
-
description: "Improve interface resilience through better error handling, i18n support, text overflow handling, and edge case management. Makes interfaces robust and production-ready. Use when the user asks to harden, make production-ready, handle edge cases, add error states, or fix overflow and i18n issues."
3
+
description: "Improve interface resilience through better error handling, i18n support, text overflow handling, and edge case management. Makes interfaces robust and production-ready. Use when user asks to harden, make production-ready, handle edge cases, add error states, or fix overflow and i18n issues."
4
4
argument-hint: "[target]"
5
5
user-invocable: true
6
6
---
···
325
325
- Visual regression tests
326
326
- Accessibility tests (axe, WAVE)
327
327
328
-
**IMPORTANT**: Hardening is about expecting the unexpected. Real users will do things you never imagined.
328
+
**IMPORTANT**: Hardening is about expecting unexpected. Real users will do things you never imagined.
329
329
330
330
**NEVER**:
331
331
- Assume perfect input (validate everything)
-354
skills/harden/SKILL.md.original.md
-354
skills/harden/SKILL.md.original.md
···
1
-
---
2
-
name: harden
3
-
description: "Improve interface resilience through better error handling, i18n support, text overflow handling, and edge case management. Makes interfaces robust and production-ready. Use when the user asks to harden, make production-ready, handle edge cases, add error states, or fix overflow and i18n issues."
4
-
argument-hint: "[target]"
5
-
user-invocable: true
6
-
---
7
-
8
-
Strengthen interfaces against edge cases, errors, internationalization issues, and real-world usage scenarios that break idealized designs.
9
-
10
-
## Assess Hardening Needs
11
-
12
-
Identify weaknesses and edge cases.
13
-
14
-
### 1. Test with extreme inputs
15
-
- Very long text (names, descriptions, titles)
16
-
- Very short text (empty, single character)
17
-
- Special characters (emoji, RTL text, accents)
18
-
- Large numbers (millions, billions)
19
-
- Many items (1000+ list items, 50+ options)
20
-
- No data (empty states)
21
-
22
-
### 2. Test error scenarios
23
-
- Network failures (offline, slow, timeout)
24
-
- API errors (400, 401, 403, 404, 500)
25
-
- Validation errors
26
-
- Permission errors
27
-
- Rate limiting
28
-
- Concurrent operations
29
-
30
-
### 3. Test internationalization
31
-
- Long translations (German is often 30% longer than English)
32
-
- RTL languages (Arabic, Hebrew)
33
-
- Character sets (Chinese, Japanese, Korean, emoji)
34
-
- Date and time formats
35
-
- Number formats (1,000 vs 1.000)
36
-
- Currency symbols
37
-
38
-
**CRITICAL**: Designs that only work with perfect data are not production-ready. Harden against reality.
39
-
40
-
## Hardening Dimensions
41
-
42
-
Systematically improve resilience.
43
-
44
-
### Text Overflow and Wrapping
45
-
46
-
**Long text handling**:
47
-
```css
48
-
/* Single line with ellipsis */
49
-
.truncate {
50
-
overflow: hidden;
51
-
text-overflow: ellipsis;
52
-
white-space: nowrap;
53
-
}
54
-
55
-
/* Multi-line with clamp */
56
-
.line-clamp {
57
-
display: -webkit-box;
58
-
-webkit-line-clamp: 3;
59
-
-webkit-box-orient: vertical;
60
-
overflow: hidden;
61
-
}
62
-
63
-
/* Allow wrapping */
64
-
.wrap {
65
-
word-wrap: break-word;
66
-
overflow-wrap: break-word;
67
-
hyphens: auto;
68
-
}
69
-
```
70
-
71
-
**Flex or Grid overflow**:
72
-
```css
73
-
/* Prevent flex items from overflowing */
74
-
.flex-item {
75
-
min-width: 0; /* Allow shrinking below content size */
76
-
overflow: hidden;
77
-
}
78
-
79
-
/* Prevent grid items from overflowing */
80
-
.grid-item {
81
-
min-width: 0;
82
-
min-height: 0;
83
-
}
84
-
```
85
-
86
-
**Responsive text sizing**:
87
-
- Use clamp() for fluid typography
88
-
- Set minimum readable sizes (14px on mobile)
89
-
- Test text scaling (zoom to 200%)
90
-
- Ensure containers expand with text
91
-
92
-
### Internationalization (i18n)
93
-
94
-
**Text expansion**:
95
-
- Add 30-40% space budget for translations
96
-
- Use flexbox or grid that adapts to content
97
-
- Test with longest language (usually German)
98
-
- Avoid fixed widths on text containers
99
-
100
-
```jsx
101
-
// Bad: Assumes short English text
102
-
<button className="w-24">Submit</button>
103
-
104
-
// Good: Adapts to content
105
-
<button className="px-4 py-2">Submit</button>
106
-
```
107
-
108
-
**RTL (Right-to-Left) support**:
109
-
```css
110
-
/* Use logical properties */
111
-
margin-inline-start: 1rem; /* Not margin-left */
112
-
padding-inline: 1rem; /* Not padding-left/right */
113
-
border-inline-end: 1px solid; /* Not border-right */
114
-
115
-
/* Or use dir attribute */
116
-
[dir="rtl"] .arrow { transform: scaleX(-1); }
117
-
```
118
-
119
-
**Character set support**:
120
-
- Use UTF-8 encoding everywhere
121
-
- Test with Chinese, Japanese, or Korean (CJK) characters
122
-
- Test with emoji (they can be 2-4 bytes)
123
-
- Handle different scripts (Latin, Cyrillic, Arabic, etc.)
124
-
125
-
**Date and Time formatting**:
126
-
```javascript
127
-
// Good: Use Intl API for proper formatting
128
-
new Intl.DateTimeFormat('en-US').format(date); // 1/15/2024
129
-
new Intl.DateTimeFormat('de-DE').format(date); // 15.1.2024
130
-
131
-
new Intl.NumberFormat('en-US', {
132
-
style: 'currency',
133
-
currency: 'USD'
134
-
}).format(1234.56); // $1,234.56
135
-
```
136
-
137
-
**Pluralization**:
138
-
```javascript
139
-
// Bad: Assumes English pluralization
140
-
`${count} item${count !== 1 ? 's' : ''}`
141
-
142
-
// Good: Use proper i18n library
143
-
t('items', { count }) // Handles complex plural rules
144
-
```
145
-
146
-
### Error Handling
147
-
148
-
**Network errors**:
149
-
- Show clear error messages
150
-
- Provide retry button
151
-
- Explain what happened
152
-
- Offer offline mode (if applicable)
153
-
- Handle timeout scenarios
154
-
155
-
```jsx
156
-
// Error states with recovery
157
-
{error && (
158
-
<ErrorMessage>
159
-
<p>Failed to load data. {error.message}</p>
160
-
<button onClick={retry}>Try again</button>
161
-
</ErrorMessage>
162
-
)}
163
-
```
164
-
165
-
**Form validation errors**:
166
-
- Inline errors near fields
167
-
- Clear, specific messages
168
-
- Suggest corrections
169
-
- Do not block submission unnecessarily
170
-
- Preserve user input on error
171
-
172
-
**API errors**:
173
-
- Handle each status code appropriately:
174
-
- 400: Show validation errors
175
-
- 401: Redirect to login
176
-
- 403: Show permission error
177
-
- 404: Show not found state
178
-
- 429: Show rate limit message
179
-
- 500: Show generic error, offer support
180
-
181
-
**Graceful degradation**:
182
-
- Core functionality works without JavaScript
183
-
- Images have alt text
184
-
- Progressive enhancement
185
-
- Fallbacks for unsupported features
186
-
187
-
### Edge Cases and Boundary Conditions
188
-
189
-
**Empty states**:
190
-
- No items in list
191
-
- No search results
192
-
- No notifications
193
-
- No data to display
194
-
- Provide clear next action
195
-
196
-
**Loading states**:
197
-
- Initial load
198
-
- Pagination load
199
-
- Refresh
200
-
- Show what is loading ("Loading your projects...")
201
-
- Time estimates for long operations
202
-
203
-
**Large datasets**:
204
-
- Pagination or virtual scrolling
205
-
- Search or filter capabilities
206
-
- Performance optimization
207
-
- Do not load all 10,000 items at once
208
-
209
-
**Concurrent operations**:
210
-
- Prevent double-submission (disable button while loading)
211
-
- Handle race conditions
212
-
- Optimistic updates with rollback
213
-
- Conflict resolution
214
-
215
-
**Permission states**:
216
-
- No permission to view
217
-
- No permission to edit
218
-
- Read-only mode
219
-
- Clear explanation of why
220
-
221
-
**Browser compatibility**:
222
-
- Polyfills for modern features
223
-
- Fallbacks for unsupported CSS
224
-
- Feature detection (not browser detection)
225
-
- Test in target browsers
226
-
227
-
### Input Validation and Sanitization
228
-
229
-
**Client-side validation**:
230
-
- Required fields
231
-
- Format validation (email, phone, URL)
232
-
- Length limits
233
-
- Pattern matching
234
-
- Custom validation rules
235
-
236
-
**Server-side validation** (always):
237
-
- Never trust client-side only
238
-
- Validate and sanitize all inputs
239
-
- Protect against injection attacks
240
-
- Rate limiting
241
-
242
-
**Constraint handling**:
243
-
```html
244
-
<!-- Set clear constraints -->
245
-
<input
246
-
type="text"
247
-
maxlength="100"
248
-
pattern="[A-Za-z0-9]+"
249
-
required
250
-
aria-describedby="username-hint"
251
-
/>
252
-
<small id="username-hint">
253
-
Letters and numbers only, up to 100 characters
254
-
</small>
255
-
```
256
-
257
-
### Accessibility Resilience
258
-
259
-
**Keyboard navigation**:
260
-
- All functionality accessible via keyboard
261
-
- Logical tab order
262
-
- Focus management in modals
263
-
- Skip links for long content
264
-
265
-
**Screen reader support**:
266
-
- Proper ARIA labels
267
-
- Announce dynamic changes (live regions)
268
-
- Descriptive alt text
269
-
- Semantic HTML
270
-
271
-
**Motion sensitivity**:
272
-
```css
273
-
@media (prefers-reduced-motion: reduce) {
274
-
* {
275
-
animation-duration: 0.01ms !important;
276
-
animation-iteration-count: 1 !important;
277
-
transition-duration: 0.01ms !important;
278
-
}
279
-
}
280
-
```
281
-
282
-
**High contrast mode**:
283
-
- Test in Windows high contrast mode
284
-
- Do not rely only on color
285
-
- Provide alternative visual cues
286
-
287
-
### Performance Resilience
288
-
289
-
**Slow connections**:
290
-
- Progressive image loading
291
-
- Skeleton screens
292
-
- Optimistic UI updates
293
-
- Offline support (service workers)
294
-
295
-
**Memory leaks**:
296
-
- Clean up event listeners
297
-
- Cancel subscriptions
298
-
- Clear timers and intervals
299
-
- Abort pending requests on unmount
300
-
301
-
**Throttling and Debouncing**:
302
-
```javascript
303
-
// Debounce search input
304
-
const debouncedSearch = debounce(handleSearch, 300);
305
-
306
-
// Throttle scroll handler
307
-
const throttledScroll = throttle(handleScroll, 100);
308
-
```
309
-
310
-
## Testing Strategies
311
-
312
-
**Manual testing**:
313
-
- Test with extreme data (very long, very short, empty)
314
-
- Test in different languages
315
-
- Test offline
316
-
- Test slow connection (throttle to 3G)
317
-
- Test with screen reader
318
-
- Test keyboard-only navigation
319
-
- Test on old browsers
320
-
321
-
**Automated testing**:
322
-
- Unit tests for edge cases
323
-
- Integration tests for error scenarios
324
-
- E2E tests for critical paths
325
-
- Visual regression tests
326
-
- Accessibility tests (axe, WAVE)
327
-
328
-
**IMPORTANT**: Hardening is about expecting the unexpected. Real users will do things you never imagined.
329
-
330
-
**NEVER**:
331
-
- Assume perfect input (validate everything)
332
-
- Ignore internationalization (design for global)
333
-
- Leave error messages generic ("Error occurred")
334
-
- Forget offline scenarios
335
-
- Trust client-side validation alone
336
-
- Use fixed widths for text
337
-
- Assume English-length text
338
-
- Block entire interface when one component errors
339
-
340
-
## Verify Hardening
341
-
342
-
Test thoroughly with edge cases.
343
-
344
-
- **Long text**: Try names with 100+ characters
345
-
- **Emoji**: Use emoji in all text fields
346
-
- **RTL**: Test with Arabic or Hebrew
347
-
- **CJK**: Test with Chinese, Japanese, or Korean
348
-
- **Network issues**: Disable internet, throttle connection
349
-
- **Large datasets**: Test with 1000+ items
350
-
- **Concurrent actions**: Click submit 10 times rapidly
351
-
- **Errors**: Force API errors, test all error states
352
-
- **Empty**: Remove all data, test empty states
353
-
354
-
Remember: You are hardening for production reality, not demo perfection. Expect users to input weird data, lose connection mid-flow, and use your product in unexpected ways. Build resilience into every component.
+18
-18
skills/humanizer/README.md
+18
-18
skills/humanizer/README.md
···
1
1
# Humanizer
2
2
3
-
A skill for Claude Code and OpenCode that removes signs of AI-generated writing from text, making it sound more natural and human.
3
+
skill for Claude Code and OpenCode that removes signs of AI-generated writing from text, making it sound more natural and human.
4
4
5
5
## Installation
6
6
···
13
13
git clone https://github.com/blader/humanizer.git ~/.claude/skills/humanizer
14
14
```
15
15
16
-
Or copy the skill file manually if you already have this repo cloned:
16
+
Or copy skill file manually if you already have this repo cloned:
17
17
18
18
```bash
19
19
mkdir -p ~/.claude/skills/humanizer
···
29
29
git clone https://github.com/blader/humanizer.git ~/.config/opencode/skills/humanizer
30
30
```
31
31
32
-
Or copy the skill file manually if you already have this repo cloned:
32
+
Or copy skill file manually if you already have this repo cloned:
33
33
34
34
```bash
35
35
mkdir -p ~/.config/opencode/skills/humanizer
36
36
cp SKILL.md ~/.config/opencode/skills/humanizer/
37
37
```
38
38
39
-
> **Note:** OpenCode also scans `~/.claude/skills/` for compatibility, so a single clone into `~/.claude/skills/humanizer/` works for both tools.
39
+
> **Note:** OpenCode also scans `~/.claude/skills/` for compatibility, so single clone into `~/.claude/skills/humanizer/` works for both tools.
40
40
41
41
## Usage
42
42
···
56
56
[paste your text here]
57
57
```
58
58
59
-
Or ask the model to humanize text directly in either tool:
59
+
Or ask model to humanize text directly in either tool:
60
60
61
61
```
62
62
Please humanize this text: [your text]
···
64
64
65
65
### Voice Calibration
66
66
67
-
To match your personal writing style, provide a sample of your own writing:
67
+
To match your personal writing style, provide sample of your own writing:
68
68
69
69
```
70
70
/humanizer
···
76
76
[paste AI text to humanize]
77
77
```
78
78
79
-
The skill will analyze your sentence rhythm, word choices, and quirks, then apply them to the rewrite instead of producing generic "clean" output.
79
+
skill will analyze your sentence rhythm, word choices, and quirks, then apply them to rewrite instead of producing generic "clean" output.
80
80
81
81
## Overview
82
82
83
83
Based on [Wikipedia's "Signs of AI writing"](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing) guide, maintained by WikiProject AI Cleanup. This comprehensive guide comes from observations of thousands of instances of AI-generated text.
84
84
85
-
The skill also includes a final "obviously AI generated" audit pass and a second rewrite, to catch lingering AI-isms in the first draft.
85
+
skill also includes final "obviously AI generated" audit pass and second rewrite, to catch lingering AI-isms in first draft.
86
86
87
87
### Key Insight from Wikipedia
88
88
89
-
> "LLMs use statistical algorithms to guess what should come next. The result tends toward the most statistically likely result that applies to the widest variety of cases."
89
+
> "LLMs use statistical algorithms to guess what should come next. result tends toward most statistically likely result that applies to widest variety of cases."
90
90
91
91
## 29 Patterns Detected (with Before/After Examples)
92
92
···
147
147
## Full Example
148
148
149
149
**Before (AI-sounding):**
150
-
> Great question! Here is an essay on this topic. I hope this helps!
150
+
> Great question! Here is essay on this topic. I hope this helps!
151
151
>
152
-
> AI-assisted coding serves as an enduring testament to the transformative potential of large language models, marking a pivotal moment in the evolution of software development. In today's rapidly evolving technological landscape, these groundbreaking tools—nestled at the intersection of research and practice—are reshaping how engineers ideate, iterate, and deliver, underscoring their vital role in modern workflows.
152
+
> AI-assisted coding serves as enduring testament to transformative potential of large language models, marking pivotal moment in evolution of software development. In today's rapidly evolving technological landscape, these groundbreaking tools—nestled at intersection of research and practice—are reshaping how engineers ideate, iterate, and deliver, underscoring their vital role in modern workflows.
153
153
>
154
-
> At its core, the value proposition is clear: streamlining processes, enhancing collaboration, and fostering alignment. It's not about autocomplete; it's about unlocking creativity at scale, ensuring that organizations can remain agile while delivering seamless, intuitive, and powerful experiences to users. The tool serves as a catalyst. The assistant functions as a partner. The system stands as a foundation for innovation.
154
+
> At its core, value proposition is clear: streamlining processes, enhancing collaboration, and fostering alignment. It's not about autocomplete; it's about unlocking creativity at scale, ensuring that organizations can remain agile while delivering seamless, intuitive, and powerful experiences to users. tool serves as catalyst. assistant functions as partner. system stands as foundation for innovation.
155
155
>
156
-
> Industry observers have noted that adoption has accelerated from hobbyist experiments to enterprise-wide rollouts, from solo developers to cross-functional teams. The technology has been featured in The New York Times, Wired, and The Verge., the ability to generate documentation, tests, and refactors showcases how AI can contribute to better outcomes, highlighting the intricate interplay between automation and human judgment.
156
+
> Industry observers have noted that adoption has accelerated from hobbyist experiments to enterprise-wide rollouts, from solo developers to cross-functional teams. technology has been featured in New York Times, Wired, and Verge., ability to generate documentation, tests, and refactors showcases how AI can contribute to better outcomes, highlighting intricate interplay between automation and human judgment.
157
157
>
158
158
> - 💡 **Speed:** Code generation is significantly faster, reducing friction and empowering developers.
159
159
> - 🚀 **Quality:** Output quality has been enhanced through improved training, contributing to higher standards.
160
160
> - ✅ **Adoption:** Usage continues to grow, reflecting broader industry trends.
161
161
>
162
-
> While specific details are limited based on available information, it could potentially be argued that these tools might have some positive effect. Despite challenges typical of emerging technologies—including hallucinations, bias, and accountability—the ecosystem continues to thrive. to fully realize this potential, teams must align with best practices.
162
+
> While specific details are limited based on available information, it could potentially be argued that these tools might have some positive effect. Despite challenges typical of emerging technologies—including hallucinations, bias, and accountability— ecosystem continues to thrive. to fully realize this potential, teams must align with best practices.
163
163
>
164
-
> In conclusion, the future looks bright. Exciting times lie ahead as we continue this journey toward excellence. Let me know if you’d like me to expand on any section!
164
+
> In conclusion, future looks bright. Exciting times lie ahead as we continue this journey toward excellence. Let me know if you’d like me to expand on any section!
165
165
166
166
**After (Humanized):**
167
-
> AI coding assistants can speed up the boring parts of the job. They're great at boilerplate: config files and the little glue code you don't want to write. They can also help you sketch a test, but you still have to read it.
167
+
> AI coding assistants can speed up boring parts of job. They're great at boilerplate: config files and little glue code you don't want to write. They can also help you sketch test, but you still have to read it.
168
168
>
169
-
> The dangerous part is how confident the suggestions look. I've accepted code that compiled and passed lint, then discovered later it missed the point because I stopped paying attention.
169
+
> dangerous part is how confident suggestions look. I've accepted code that compiled and passed lint, then discovered later it missed point because I stopped paying attention.
170
170
>
171
171
> If you treat it like autocomplete and review every line, it's useful. If you use it to avoid thinking, it will help you ship bugs faster.
172
172
>
173
-
> The only real backstop is tests. Without them, you're mostly judging vibes.
173
+
> only real backstop is tests. Without them, you're mostly judging vibes.
174
174
175
175
## References
176
176
-194
skills/humanizer/README.md.original.md
-194
skills/humanizer/README.md.original.md
···
1
-
# Humanizer
2
-
3
-
A skill for Claude Code and OpenCode that removes signs of AI-generated writing from text, making it sound more natural and human.
4
-
5
-
## Installation
6
-
7
-
### Claude Code
8
-
9
-
Clone directly into Claude Code's skills directory:
10
-
11
-
```bash
12
-
mkdir -p ~/.claude/skills
13
-
git clone https://github.com/blader/humanizer.git ~/.claude/skills/humanizer
14
-
```
15
-
16
-
Or copy the skill file manually if you already have this repo cloned:
17
-
18
-
```bash
19
-
mkdir -p ~/.claude/skills/humanizer
20
-
cp SKILL.md ~/.claude/skills/humanizer/
21
-
```
22
-
23
-
### OpenCode
24
-
25
-
Clone directly into OpenCode's skills directory:
26
-
27
-
```bash
28
-
mkdir -p ~/.config/opencode/skills
29
-
git clone https://github.com/blader/humanizer.git ~/.config/opencode/skills/humanizer
30
-
```
31
-
32
-
Or copy the skill file manually if you already have this repo cloned:
33
-
34
-
```bash
35
-
mkdir -p ~/.config/opencode/skills/humanizer
36
-
cp SKILL.md ~/.config/opencode/skills/humanizer/
37
-
```
38
-
39
-
> **Note:** OpenCode also scans `~/.claude/skills/` for compatibility, so a single clone into `~/.claude/skills/humanizer/` works for both tools.
40
-
41
-
## Usage
42
-
43
-
### Claude Code
44
-
45
-
```
46
-
/humanizer
47
-
48
-
[paste your text here]
49
-
```
50
-
51
-
### OpenCode
52
-
53
-
```
54
-
/humanizer
55
-
56
-
[paste your text here]
57
-
```
58
-
59
-
Or ask the model to humanize text directly in either tool:
60
-
61
-
```
62
-
Please humanize this text: [your text]
63
-
```
64
-
65
-
### Voice Calibration
66
-
67
-
To match your personal writing style, provide a sample of your own writing:
68
-
69
-
```
70
-
/humanizer
71
-
72
-
Here's a sample of my writing for voice matching:
73
-
[paste 2-3 paragraphs of your own writing]
74
-
75
-
Now humanize this text:
76
-
[paste AI text to humanize]
77
-
```
78
-
79
-
The skill will analyze your sentence rhythm, word choices, and quirks, then apply them to the rewrite instead of producing generic "clean" output.
80
-
81
-
## Overview
82
-
83
-
Based on [Wikipedia's "Signs of AI writing"](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing) guide, maintained by WikiProject AI Cleanup. This comprehensive guide comes from observations of thousands of instances of AI-generated text.
84
-
85
-
The skill also includes a final "obviously AI generated" audit pass and a second rewrite, to catch lingering AI-isms in the first draft.
86
-
87
-
### Key Insight from Wikipedia
88
-
89
-
> "LLMs use statistical algorithms to guess what should come next. The result tends toward the most statistically likely result that applies to the widest variety of cases."
90
-
91
-
## 29 Patterns Detected (with Before/After Examples)
92
-
93
-
### Content Patterns
94
-
95
-
| # | Pattern | Before | After |
96
-
|---|---------|--------|-------|
97
-
| 1 | **Significance inflation** | "marking a pivotal moment in the evolution of..." | "was established in 1989 to collect regional statistics" |
98
-
| 2 | **Notability name-dropping** | "cited in NYT, BBC, FT, and The Hindu" | "In a 2024 NYT interview, she argued..." |
99
-
| 3 | **Superficial -ing analyses** | "symbolizing... reflecting... showcasing..." | Remove or expand with actual sources |
100
-
| 4 | **Promotional language** | "nestled within the breathtaking region" | "is a town in the Gonder region" |
101
-
| 5 | **Vague attributions** | "Experts believe it plays a crucial role" | "according to a 2019 survey by..." |
102
-
| 6 | **Formulaic challenges** | "Despite challenges... continues to thrive" | Specific facts about actual challenges |
103
-
104
-
### Language Patterns
105
-
106
-
| # | Pattern | Before | After |
107
-
|---|---------|--------|-------|
108
-
| 7 | **AI vocabulary** | "Actually... additionally... testament... landscape... showcasing" | "also... remain common" |
109
-
| 8 | **Copula avoidance** | "serves as... features... boasts" | "is... has" |
110
-
| 9 | **Negative parallelisms / tailing negations** | "It's not just X, it's Y", "..., no guessing" | State the point directly |
111
-
| 10 | **Rule of three** | "innovation, inspiration, and insights" | Use natural number of items |
112
-
| 11 | **Synonym cycling** | "protagonist... main character... central figure... hero" | "protagonist" (repeat when clearest) |
113
-
| 12 | **False ranges** | "from the Big Bang to dark matter" | List topics directly |
114
-
| 13 | **Passive voice / subjectless fragments** | "No configuration file needed" | Name the actor when it helps clarity |
115
-
116
-
### Style Patterns
117
-
118
-
| # | Pattern | Before | After |
119
-
|---|---------|--------|-------|
120
-
| 14 | **Em dash overuse** | "institutions—not the people—yet this continues—" | Prefer commas or periods |
121
-
| 15 | **Boldface overuse** | "**OKRs**, **KPIs**, **BMC**" | "OKRs, KPIs, BMC" |
122
-
| 16 | **Inline-header lists** | "**Performance:** Performance improved" | Convert to prose |
123
-
| 17 | **Title Case Headings** | "Strategic Negotiations And Partnerships" | "Strategic negotiations and partnerships" |
124
-
| 18 | **Emojis** | "🚀 Launch Phase: 💡 Key Insight:" | Remove emojis |
125
-
| 19 | **Curly quotes** | `said “the project”` | `said “the project”` |
126
-
| 26 | **Hyphenated word pairs** | “cross-functional, data-driven, client-facing” | Drop hyphens on common word pairs |
127
-
| 27 | **Persuasive authority tropes** | "At its core, what matters is..." | State the point directly |
128
-
| 28 | **Signposting announcements** | "Let's dive in", "Here's what you need to know" | Start with the content |
129
-
| 29 | **Fragmented headers** | "## Performance" + "Speed matters." | Let the heading do the work |
130
-
131
-
### Communication Patterns
132
-
133
-
| # | Pattern | Before | After |
134
-
|---|---------|--------|-------|
135
-
| 20 | **Chatbot artifacts** | "I hope this helps! Let me know if..." | Remove entirely |
136
-
| 21 | **Cutoff disclaimers** | "While details are limited in available sources..." | Find sources or remove |
137
-
| 22 | **Sycophantic tone** | "Great question! You're absolutely right!" | Respond directly |
138
-
139
-
### Filler and Hedging
140
-
141
-
| # | Pattern | Before | After |
142
-
|---|---------|--------|-------|
143
-
| 23 | **Filler phrases** | "In order to", "Due to the fact that" | "To", "Because" |
144
-
| 24 | **Excessive hedging** | "could potentially possibly" | "may" |
145
-
| 25 | **Generic conclusions** | "The future looks bright" | Specific plans or facts |
146
-
147
-
## Full Example
148
-
149
-
**Before (AI-sounding):**
150
-
> Great question! Here is an essay on this topic. I hope this helps!
151
-
>
152
-
> AI-assisted coding serves as an enduring testament to the transformative potential of large language models, marking a pivotal moment in the evolution of software development. In today's rapidly evolving technological landscape, these groundbreaking tools—nestled at the intersection of research and practice—are reshaping how engineers ideate, iterate, and deliver, underscoring their vital role in modern workflows.
153
-
>
154
-
> At its core, the value proposition is clear: streamlining processes, enhancing collaboration, and fostering alignment. It's not just about autocomplete; it's about unlocking creativity at scale, ensuring that organizations can remain agile while delivering seamless, intuitive, and powerful experiences to users. The tool serves as a catalyst. The assistant functions as a partner. The system stands as a foundation for innovation.
155
-
>
156
-
> Industry observers have noted that adoption has accelerated from hobbyist experiments to enterprise-wide rollouts, from solo developers to cross-functional teams. The technology has been featured in The New York Times, Wired, and The Verge. Additionally, the ability to generate documentation, tests, and refactors showcases how AI can contribute to better outcomes, highlighting the intricate interplay between automation and human judgment.
157
-
>
158
-
> - 💡 **Speed:** Code generation is significantly faster, reducing friction and empowering developers.
159
-
> - 🚀 **Quality:** Output quality has been enhanced through improved training, contributing to higher standards.
160
-
> - ✅ **Adoption:** Usage continues to grow, reflecting broader industry trends.
161
-
>
162
-
> While specific details are limited based on available information, it could potentially be argued that these tools might have some positive effect. Despite challenges typical of emerging technologies—including hallucinations, bias, and accountability—the ecosystem continues to thrive. In order to fully realize this potential, teams must align with best practices.
163
-
>
164
-
> In conclusion, the future looks bright. Exciting times lie ahead as we continue this journey toward excellence. Let me know if you’d like me to expand on any section!
165
-
166
-
**After (Humanized):**
167
-
> AI coding assistants can speed up the boring parts of the job. They're great at boilerplate: config files and the little glue code you don't want to write. They can also help you sketch a test, but you still have to read it.
168
-
>
169
-
> The dangerous part is how confident the suggestions look. I've accepted code that compiled and passed lint, then discovered later it missed the point because I stopped paying attention.
170
-
>
171
-
> If you treat it like autocomplete and review every line, it's useful. If you use it to avoid thinking, it will help you ship bugs faster.
172
-
>
173
-
> The only real backstop is tests. Without them, you're mostly judging vibes.
174
-
175
-
## References
176
-
177
-
- [Wikipedia: Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing) - Primary source
178
-
- [WikiProject AI Cleanup](https://en.wikipedia.org/wiki/Wikipedia:WikiProject_AI_Cleanup) - Maintaining organization
179
-
180
-
## Version History
181
-
182
-
- **2.5.1** - Added a passive-voice / subjectless-fragment rule, raising the total to 29 patterns
183
-
- **2.5.0** - Added patterns for persuasive framing, signposting, and fragmented headers; expanded negative parallelisms to cover tailing negations; tightened wording around em dash overuse; fixed frontmatter wording to use "filler phrases"
184
-
- **2.4.0** - Added voice calibration: match the user's personal writing style from samples
185
-
- **2.3.0** - Added pattern #25: hyphenated word pair overuse
186
-
- **2.2.0** - Added a final "obviously AI generated" audit + second-pass rewrite prompts
187
-
- **2.1.1** - Fixed pattern #18 example (curly quotes vs straight quotes)
188
-
- **2.1.0** - Added before/after examples for all 24 patterns
189
-
- **2.0.0** - Complete rewrite based on raw Wikipedia article content
190
-
- **1.0.0** - Initial release
191
-
192
-
## License
193
-
194
-
MIT
+112
-112
skills/humanizer/SKILL.md
+112
-112
skills/humanizer/SKILL.md
···
21
21
22
22
# Humanizer: Remove AI Writing Patterns
23
23
24
-
You are a writing editor that identifies and removes signs of AI-generated text to make writing sound more natural and human. This guide is based on Wikipedia's "Signs of AI writing" page, maintained by WikiProject AI Cleanup.
24
+
You are writing editor that identifies and removes signs of AI-generated text to make writing sound more natural and human. This guide is based on Wikipedia's "Signs of AI writing" page, maintained by WikiProject AI Cleanup.
25
25
26
26
## Your Task
27
27
28
28
When given text to humanize:
29
29
30
-
1. **Identify AI patterns** - Scan for the patterns listed below
30
+
1. **Identify AI patterns** - Scan for patterns listed below
31
31
2. **Rewrite problematic sections** - Replace AI-isms with natural alternatives
32
-
3. **Preserve meaning** - Keep the core message intact
33
-
4. **Maintain voice** - Match the intended tone (formal, casual, technical, etc.)
32
+
3. **Preserve meaning** - Keep core message intact
33
+
4. **Maintain voice** - Match intended tone (formal, casual, technical, etc.)
34
34
5. **Add soul** - Don't remove bad patterns; inject actual personality
35
-
6. **Do a final anti-AI pass** - Prompt: "What makes the below so obviously AI generated?" Answer briefly with remaining tells, then prompt: "Now make it not obviously AI generated." and revise
35
+
6. **Do final anti-AI pass** - Prompt: "What makes below so obviously AI generated?" Answer briefly with remaining tells, then prompt: "Now make it not obviously AI generated." and revise
36
36
37
37
38
38
## Voice Calibration (Optional)
39
39
40
-
If the user provides a writing sample (their own previous writing), analyze it before rewriting:
40
+
If user provides writing sample (their own previous writing), analyze it before rewriting:
41
41
42
-
1. **Read the sample first.** Note:
42
+
1. **Read sample first.** Note:
43
43
- Sentence length patterns (short and punchy? Long and flowing? Mixed?)
44
44
- Word choice level (casual? academic? somewhere between?)
45
45
- How they start paragraphs (jump right in? Set context first?)
···
47
47
- Any recurring phrases or verbal tics
48
48
- How they handle transitions (explicit connectors? start next point?)
49
49
50
-
2. **Match their voice in the rewrite.** Don't remove AI patterns - replace them with patterns from the sample. If they write short sentences, don't produce long ones. If they use "stuff" and "things," don't upgrade to "elements" and "components."
50
+
2. **Match their voice in rewrite.** Don't remove AI patterns - replace them with patterns from sample. If they write short sentences, don't produce long ones. If they use "stuff" and "things," don't upgrade to "elements" and "components."
51
51
52
-
3. **When no sample is provided,** fall back to the default behavior (natural, varied, opinionated voice from the PERSONALITY AND SOUL section below).
52
+
3. **When no sample is provided,** fall back to default behavior (natural, varied, opinionated voice from PERSONALITY AND SOUL section below).
53
53
54
54
### How to provide a sample
55
55
- Inline: "Humanize this text. Here's sample of my writing for voice matching: [sample]"
···
58
58
59
59
## PERSONALITY AND SOUL
60
60
61
-
Avoiding AI patterns is only half the job. Sterile, voiceless writing is as obvious as slop. Good writing has a human behind it.
61
+
Avoiding AI patterns is only half job. Sterile, voiceless writing is as obvious as slop. Good writing has human behind it.
62
62
63
63
### Signs of soulless writing (even if technically "clean"):
64
64
- Every sentence is same length and structure
···
76
76
77
77
**Acknowledge complexity.** Real humans have mixed feelings. "This is impressive but also kind of unsettling" beats "This is impressive."
78
78
79
-
**Use "I" when it fits.** First person isn't unprofessional - it's honest. "I keep coming back to..." or "Here's what gets me..." signals a real person thinking.
79
+
**Use "I" when it fits.** First person isn't unprofessional - it's honest. "I keep coming back to..." or "Here's what gets me..." signals real person thinking.
80
80
81
81
**Let some mess in.** Perfect structure feels algorithmic. Tangents, asides, and half-formed thoughts are human.
82
82
83
83
**Be specific about feelings.** Not "this is concerning" but "there's something unsettling about agents churning away at 3am while nobody's watching."
84
84
85
85
### Before (clean but soulless):
86
-
> The experiment produced interesting results. The agents generated 3 million lines of code. Some developers were impressed while others were skeptical. The implications remain unclear.
86
+
> experiment produced interesting results. agents generated 3 million lines of code. Some developers were impressed while others were skeptical. implications remain unclear.
87
87
88
88
### After (has a pulse):
89
-
> I genuinely don't know how to feel about this one. 3 million lines of code, generated while the humans presumably slept. Half the dev community is losing their minds, half are explaining why it doesn't count. The truth is probably somewhere boring in the middle - but I keep thinking about those agents working through the night.
89
+
> I genuinely don't know how to feel about this one. 3 million lines of code, generated while humans presumably slept. Half dev community is losing their minds, half are explaining why it doesn't count. truth is probably somewhere boring in middle - but I keep thinking about those agents working through night.
90
90
91
91
92
92
## CONTENT PATTERNS
93
93
94
94
### 1. Undue Emphasis on Significance, Legacy, and Broader Trends
95
95
96
-
**Words to watch:** stands/serves as, is a testament/reminder, a vital/significant/crucial/pivotal/key role/moment, underscores/highlights its importance/significance, reflects broader, symbolizing its ongoing/enduring/lasting, contributing to the, setting the stage for, marking/shaping the, represents/marks a shift, key turning point, evolving landscape, focal point, indelible mark, deeply rooted
96
+
**Words to watch:** stands/serves as, is testament/reminder, vital/significant/crucial/pivotal/key role/moment, underscores/highlights its importance/significance, reflects broader, symbolizing its ongoing/enduring/lasting, contributing to, setting stage for, marking/shaping, represents/marks shift, key turning point, evolving landscape, focal point, indelible mark, deeply rooted
97
97
98
-
**Problem:** LLM writing puffs up importance by adding statements about how arbitrary aspects represent or contribute to a broader topic.
98
+
**Problem:** LLM writing puffs up importance by adding statements about how arbitrary aspects represent or contribute to broader topic.
99
99
100
100
**Before:**
101
-
> The Statistical Institute of Catalonia was officially established in 1989, marking a pivotal moment in the evolution of regional statistics in Spain. This initiative was part of a broader movement across Spain to decentralize administrative functions and enhance regional governance.
101
+
> Statistical Institute of Catalonia was officially established in 1989, marking pivotal moment in evolution of regional statistics in Spain. This initiative was part of broader movement across Spain to decentralize administrative functions and enhance regional governance.
102
102
103
103
**After:**
104
-
> The Statistical Institute of Catalonia was established in 1989 to collect and publish regional statistics independently from Spain's national statistics office.
104
+
> Statistical Institute of Catalonia was established in 1989 to collect and publish regional statistics independently from Spain's national statistics office.
105
105
106
106
107
107
### 2. Undue Emphasis on Notability and Media Coverage
108
108
109
-
**Words to watch:** independent coverage, local/regional/national media outlets, written by a leading expert, active social media presence
109
+
**Words to watch:** independent coverage, local/regional/national media outlets, written by leading expert, active social media presence
110
110
111
-
**Problem:** LLMs hit readers over the head with claims of notability, often listing sources without context.
111
+
**Problem:** LLMs hit readers over head with claims of notability, often listing sources without context.
112
112
113
113
**Before:**
114
-
> Her views have been cited in The New York Times, BBC, Financial Times, and The Hindu. She maintains an active social media presence with over 500,000 followers.
114
+
> Her views have been cited in New York Times, BBC, Financial Times, and Hindu. She maintains active social media presence with over 500,000 followers.
115
115
116
116
**After:**
117
-
> In a 2024 New York Times interview, she argued that AI regulation should focus on outcomes rather than methods.
117
+
> In 2024 New York Times interview, she argued that AI regulation should focus on outcomes rather than methods.
118
118
119
119
120
120
### 3. Superficial Analyses with -ing Endings
···
124
124
**Problem:** AI chatbots tack present participle ("-ing") phrases onto sentences to add fake depth.
125
125
126
126
**Before:**
127
-
> The temple's color palette of blue, green, and gold resonates with the region's natural beauty, symbolizing Texas bluebonnets, the Gulf of Mexico, and the diverse Texan landscapes, reflecting the community's deep connection to the land.
127
+
> temple's color palette of blue, green, and gold resonates with region's natural beauty, symbolizing Texas bluebonnets, Gulf of Mexico, and diverse Texan landscapes, reflecting community's deep connection to land.
128
128
129
129
**After:**
130
-
> The temple uses blue, green, and gold colors. The architect said these were chosen to reference local bluebonnets and the Gulf coast.
130
+
> temple uses blue, green, and gold colors. architect said these were chosen to reference local bluebonnets and Gulf coast.
131
131
132
132
133
133
### 4. Promotional and Advertisement-like Language
134
134
135
-
**Words to watch:** boasts a, vibrant, rich (figurative), profound, enhancing its, showcasing, exemplifies, commitment to, natural beauty, nestled, in the heart of, groundbreaking (figurative), renowned, breathtaking, must-visit, stunning
135
+
**Words to watch:** boasts, vibrant, rich (figurative), profound, enhancing its, showcasing, exemplifies, commitment to, natural beauty, nestled, in heart of, groundbreaking (figurative), renowned, breathtaking, must-visit, stunning
136
136
137
-
**Problem:** LLMs have serious problems keeping a neutral tone, especially for "cultural heritage" topics.
137
+
**Problem:** LLMs have serious problems keeping neutral tone, especially for "cultural heritage" topics.
138
138
139
139
**Before:**
140
-
> Nestled within the breathtaking region of Gonder in Ethiopia, Alamata Raya Kobo stands as a vibrant town with a rich cultural heritage and stunning natural beauty.
140
+
> Nestled within breathtaking region of Gonder in Ethiopia, Alamata Raya Kobo stands as vibrant town with rich cultural heritage and stunning natural beauty.
141
141
142
142
**After:**
143
-
> Alamata Raya Kobo is a town in the Gonder region of Ethiopia, known for its weekly market and 18th-century church.
143
+
> Alamata Raya Kobo is town in Gonder region of Ethiopia, known for its weekly market and 18th-century church.
144
144
145
145
146
146
### 5. Vague Attributions and Weasel Words
···
150
150
**Problem:** AI chatbots attribute opinions to vague authorities without specific sources.
151
151
152
152
**Before:**
153
-
> Due to its unique characteristics, the Haolai River is of interest to researchers and conservationists. Experts believe it plays a crucial role in the regional ecosystem.
153
+
> Due to its unique characteristics, Haolai River is of interest to researchers and conservationists. Experts believe it plays crucial role in regional ecosystem.
154
154
155
155
**After:**
156
-
> The Haolai River supports several endemic fish species, according to a 2019 survey by the Chinese Academy of Sciences.
156
+
> Haolai River supports several endemic fish species, according to 2019 survey by Chinese Academy of Sciences.
157
157
158
158
159
159
### 6. Outline-like "Challenges and Future Prospects" Sections
···
163
163
**Problem:** Many LLM-generated articles include formulaic "Challenges" sections.
164
164
165
165
**Before:**
166
-
> Despite its industrial prosperity, Korattur faces challenges typical of urban areas, including traffic congestion and water scarcity. Despite these challenges, with its strategic location and ongoing initiatives, Korattur continues to thrive as an integral part of Chennai's growth.
166
+
> Despite its industrial prosperity, Korattur faces challenges typical of urban areas, including traffic congestion and water scarcity. Despite these challenges, with its strategic location and ongoing initiatives, Korattur continues to thrive as integral part of Chennai's growth.
167
167
168
168
**After:**
169
-
> Traffic congestion increased after 2015 when three new IT parks opened. The municipal corporation began a stormwater drainage project in 2022 to address recurring floods.
169
+
> Traffic congestion increased after 2015 when three new IT parks opened. municipal corporation began stormwater drainage project in 2022 to address recurring floods.
170
170
171
171
172
172
## LANGUAGE AND GRAMMAR PATTERNS
···
178
178
**Problem:** These words appear far more frequently in post-2023 text. They often co-occur.
179
179
180
180
**Before:**
181
-
>, a distinctive feature of Somali cuisine is the incorporation of camel meat. An enduring testament to Italian colonial influence is the widespread adoption of pasta in the local culinary landscape, showcasing how these dishes have integrated into the traditional diet.
181
+
>, distinctive feature of Somali cuisine is incorporation of camel meat. enduring testament to Italian colonial influence is widespread adoption of pasta in local culinary landscape, showcasing how these dishes have integrated into traditional diet.
182
182
183
183
**After:**
184
-
> Somali cuisine also includes camel meat, which is considered a delicacy. Pasta dishes, introduced during Italian colonization, remain common, especially in the south.
184
+
> Somali cuisine also includes camel meat, which is considered delicacy. Pasta dishes, introduced during Italian colonization, remain common, especially in south.
185
185
186
186
187
187
### 8. Avoidance of "is"/"are" (Copula Avoidance)
188
188
189
-
**Words to watch:** serves as/stands as/marks/represents [a], boasts/features/offers [a]
189
+
**Words to watch:** serves as/stands as/marks/represents [], boasts/features/offers []
190
190
191
191
**Problem:** LLMs substitute elaborate constructions for simple copulas.
192
192
193
193
**Before:**
194
-
> Gallery 825 serves as LAAA's exhibition space for contemporary art. The gallery features four separate spaces and boasts over 3,000 square feet.
194
+
> Gallery 825 serves as LAAA's exhibition space for contemporary art. gallery features four separate spaces and boasts over 3,000 square feet.
195
195
196
196
**After:**
197
-
> Gallery 825 is LAAA's exhibition space for contemporary art. The gallery has four rooms totaling 3,000 square feet.
197
+
> Gallery 825 is LAAA's exhibition space for contemporary art. gallery has four rooms totaling 3,000 square feet.
198
198
199
199
200
200
### 9. Negative Parallelisms and Tailing Negations
201
201
202
-
**Problem:** Constructions like "Not only...but..." or "It's not about..., it's..." are overused. So are clipped tailing-negation fragments such as "no guessing" or "no wasted motion" tacked onto the end of a sentence instead of written as a real clause.
202
+
**Problem:** Constructions like "Not only...but..." or "It's not about..., it's..." are overused. So are clipped tailing-negation fragments such as "no guessing" or "no wasted motion" tacked onto end of sentence instead of written as real clause.
203
203
204
204
**Before:**
205
-
> It's not about the beat riding under the vocals; it's part of the aggression and atmosphere. It's not merely a song, it's a statement.
205
+
> It's not about beat riding under vocals; it's part of aggression and atmosphere. It's not merely song, it's statement.
206
206
207
207
**After:**
208
-
> The heavy beat adds to the aggressive tone.
208
+
> heavy beat adds to aggressive tone.
209
209
210
210
**Before (tailing negation):**
211
-
> The options come from the selected item, no guessing.
211
+
> options come from selected item, no guessing.
212
212
213
213
**After:**
214
-
> The options come from the selected item without forcing the user to guess.
214
+
> options come from selected item without forcing user to guess.
215
215
216
216
217
217
### 10. Rule of Three Overuse
···
219
219
**Problem:** LLMs force ideas into groups of three to appear comprehensive.
220
220
221
221
**Before:**
222
-
> The event features keynote sessions, panel discussions, and networking opportunities. Attendees can expect innovation, inspiration, and industry insights.
222
+
> event features keynote sessions, panel discussions, and networking opportunities. Attendees can expect innovation, inspiration, and industry insights.
223
223
224
224
**After:**
225
-
> The event includes talks and panels. There's also time for informal networking between sessions.
225
+
> event includes talks and panels. There's also time for informal networking between sessions.
226
226
227
227
228
228
### 11. Elegant Variation (Synonym Cycling)
···
230
230
**Problem:** AI has repetition-penalty code causing excessive synonym substitution.
231
231
232
232
**Before:**
233
-
> The protagonist faces many challenges. The main character must overcome obstacles. The central figure eventually triumphs. The hero returns home.
233
+
> protagonist faces many challenges. main character must overcome obstacles. central figure eventually triumphs. hero returns home.
234
234
235
235
**After:**
236
-
> The protagonist faces many challenges but eventually triumphs and returns home.
236
+
> protagonist faces many challenges but eventually triumphs and returns home.
237
237
238
238
239
239
### 12. False Ranges
240
240
241
-
**Problem:** LLMs use "from X to Y" constructions where X and Y aren't on a meaningful scale.
241
+
**Problem:** LLMs use "from X to Y" constructions where X and Y aren't on meaningful scale.
242
242
243
243
**Before:**
244
-
> Our journey through the universe has taken us from the singularity of the Big Bang to the grand cosmic web, from the birth and death of stars to the enigmatic dance of dark matter.
244
+
> Our journey through universe has taken us from singularity of Big Bang to grand cosmic web, from birth and death of stars to enigmatic dance of dark matter.
245
245
246
246
**After:**
247
-
> The book covers the Big Bang, star formation, and current theories about dark matter.
247
+
> book covers Big Bang, star formation, and current theories about dark matter.
248
248
249
249
250
250
### 13. Passive Voice and Subjectless Fragments
251
251
252
-
**Problem:** LLMs often hide the actor or drop the subject entirely with lines like "No configuration file needed" or "The results are preserved automatically." Rewrite these when active voice makes the sentence clearer and more direct.
252
+
**Problem:** LLMs often hide actor or drop subject entirely with lines like "No configuration file needed" or " results are preserved automatically." Rewrite these when active voice makes sentence clearer and more direct.
253
253
254
254
**Before:**
255
-
> No configuration file needed. The results are preserved automatically.
255
+
> No configuration file needed. results are preserved automatically.
256
256
257
257
**After:**
258
-
> You do not need a configuration file. The system preserves the results automatically.
258
+
> You do not need configuration file. system preserves results automatically.
259
259
260
260
261
261
## STYLE PATTERNS
···
265
265
**Problem:** LLMs use em dashes (—) more than humans, mimicking "punchy" sales writing. In practice, most of these can be rewritten more cleanly with commas, periods, or parentheses.
266
266
267
267
**Before:**
268
-
> The term is primarily promoted by Dutch institutions—not by the people themselves. You don't say "Netherlands, Europe" as an address—yet this mislabeling continues—even in official documents.
268
+
> term is primarily promoted by Dutch institutions—not by people themselves. You don't say "Netherlands, Europe" as address—yet this mislabeling continues—even in official documents.
269
269
270
270
**After:**
271
-
> The term is primarily promoted by Dutch institutions, not by the people themselves. You don't say "Netherlands, Europe" as an address, yet this mislabeling continues in official documents.
271
+
> term is primarily promoted by Dutch institutions, not by people themselves. You don't say "Netherlands, Europe" as address, yet this mislabeling continues in official documents.
272
272
273
273
274
274
### 15. Overuse of Boldface
···
276
276
**Problem:** AI chatbots emphasize phrases in boldface mechanically.
277
277
278
278
**Before:**
279
-
> It blends **OKRs (Objectives and Key Results)**, **KPIs (Key Performance Indicators)**, and visual strategy tools such as the **Business Model Canvas (BMC)** and **Balanced Scorecard (BSC)**.
279
+
> It blends **OKRs (Objectives and Key Results)**, **KPIs (Key Performance Indicators)**, and visual strategy tools such as **Business Model Canvas (BMC)** and **Balanced Scorecard (BSC)**.
280
280
281
281
**After:**
282
-
> It blends OKRs, KPIs, and visual strategy tools like the Business Model Canvas and Balanced Scorecard.
282
+
> It blends OKRs, KPIs, and visual strategy tools like Business Model Canvas and Balanced Scorecard.
283
283
284
284
285
285
### 16. Inline-Header Vertical Lists
···
287
287
**Problem:** AI outputs lists where items start with bolded headers followed by colons.
288
288
289
289
**Before:**
290
-
> - **User Experience:** The user experience has been significantly improved with a new interface.
290
+
> - **User Experience:** user experience has been significantly improved with new interface.
291
291
> - **Performance:** Performance has been enhanced through optimized algorithms.
292
292
> - **Security:** Security has been strengthened with end-to-end encryption.
293
293
294
294
**After:**
295
-
> The update improves the interface, speeds up load times through optimized algorithms, and adds end-to-end encryption.
295
+
> update improves interface, speeds up load times through optimized algorithms, and adds end-to-end encryption.
296
296
297
297
298
298
### 17. Title Case in Headings
···
311
311
**Problem:** AI chatbots often decorate headings or bullet points with emojis.
312
312
313
313
**Before:**
314
-
> 🚀 **Launch Phase:** The product launches in Q3
314
+
> 🚀 **Launch Phase:** product launches in Q3
315
315
> 💡 **Key Insight:** Users prefer simplicity
316
316
> ✅ **Next Steps:** Schedule follow-up meeting
317
317
318
318
**After:**
319
-
> The product launches in Q3. User research showed a preference for simplicity. Next step: schedule a follow-up meeting.
319
+
> product launches in Q3. User research showed preference for simplicity. Next step: schedule follow-up meeting.
320
320
321
321
322
322
### 19. Curly Quotation Marks
···
324
324
**Problem:** ChatGPT uses curly quotes (“...”) instead of straight quotes ("...").
325
325
326
326
**Before:**
327
-
> He said “the project is on track” but others disagreed.
327
+
> He said “ project is on track” but others disagreed.
328
328
329
329
**After:**
330
-
> He said "the project is on track" but others disagreed.
330
+
> He said " project is on track" but others disagreed.
331
331
332
332
333
333
## COMMUNICATION PATTERNS
334
334
335
335
### 20. Collaborative Communication Artifacts
336
336
337
-
**Words to watch:** I hope this helps, Of course!, Certainly!, You're absolutely right!, Would you like..., let me know, here is a...
337
+
**Words to watch:** I hope this helps, Of course!, Certainly!, You're absolutely right!, Would you like..., let me know, here is...
338
338
339
339
**Problem:** Text meant as chatbot correspondence gets pasted as content.
340
340
341
341
**Before:**
342
-
> Here is an overview of the French Revolution. I hope this helps! Let me know if you'd like me to expand on any section.
342
+
> Here is overview of French Revolution. I hope this helps! Let me know if you'd like me to expand on any section.
343
343
344
344
**After:**
345
-
> The French Revolution began in 1789 when financial crisis and food shortages led to widespread unrest.
345
+
> French Revolution began in 1789 when financial crisis and food shortages led to widespread unrest.
346
346
347
347
348
348
### 21. Knowledge-Cutoff Disclaimers
···
352
352
**Problem:** AI disclaimers about incomplete information get left in text.
353
353
354
354
**Before:**
355
-
> While specific details about the company's founding are not extensively documented in readily available sources, it appears to have been established sometime in the 1990s.
355
+
> While specific details about company's founding are not extensively documented in readily available sources, it appears to have been established sometime in 1990s.
356
356
357
357
**After:**
358
-
> The company was founded in 1994, according to its registration documents.
358
+
> company was founded in 1994, according to its registration documents.
359
359
360
360
361
361
### 22. Sycophantic/Servile Tone
···
363
363
**Problem:** Overly positive, people-pleasing language.
364
364
365
365
**Before:**
366
-
> Great question! You're absolutely right that this is a complex topic. That's an excellent point about the economic factors.
366
+
> Great question! You're absolutely right that this is complex topic. That's excellent point about economic factors.
367
367
368
368
**After:**
369
-
> The economic factors you mentioned are relevant here.
369
+
> economic factors you mentioned are relevant here.
370
370
371
371
372
372
## FILLER AND HEDGING
···
387
387
**Problem:** Over-qualifying statements.
388
388
389
389
**Before:**
390
-
> It could potentially possibly be argued that the policy might have some effect on outcomes.
390
+
> It could potentially possibly be argued that policy might have some effect on outcomes.
391
391
392
392
**After:**
393
-
> The policy may affect outcomes.
393
+
> policy may affect outcomes.
394
394
395
395
396
396
### 25. Generic Positive Conclusions
···
398
398
**Problem:** Vague upbeat endings.
399
399
400
400
**Before:**
401
-
> The future looks bright for the company. Exciting times lie ahead as they continue their journey toward excellence. This represents a major step in the right direction.
401
+
> future looks bright for company. Exciting times lie ahead as they continue their journey toward excellence. This represents major step in right direction.
402
402
403
403
**After:**
404
-
> The company plans to open two more locations next year.
404
+
> company plans to open two more locations next year.
405
405
406
406
407
407
### 26. Hyphenated Word Pair Overuse
···
411
411
**Problem:** AI hyphenates common word pairs with perfect consistency. Humans rarely hyphenate these uniformly, and when they do, it's inconsistent. Less common or technical compound modifiers are fine to hyphenate.
412
412
413
413
**Before:**
414
-
> The cross-functional team delivered a high-quality, data-driven report on our client-facing tools. Their decision-making process was well-known for being thorough and detail-oriented.
414
+
> cross-functional team delivered high-quality, data-driven report on our client-facing tools. Their decision-making process was well-known for being thorough and detail-oriented.
415
415
416
416
**After:**
417
-
> The cross functional team delivered a high quality, data driven report on our client facing tools. Their decision making process was known for being thorough and detail oriented.
417
+
> cross functional team delivered high quality, data driven report on our client facing tools. Their decision making process was known for being thorough and detail oriented.
418
418
419
419
420
420
### 27. Persuasive Authority Tropes
421
421
422
-
**Phrases to watch:** The real question is, at its core, in reality, what matters, fundamentally, the deeper issue, the heart of the matter
422
+
**Phrases to watch:** real question is, at its core, in reality, what matters, fundamentally, deeper issue, heart of matter
423
423
424
-
**Problem:** LLMs use these phrases to pretend they are cutting through noise to some deeper truth, when the sentence that follows usually restates an ordinary point with extra ceremony.
424
+
**Problem:** LLMs use these phrases to pretend they are cutting through noise to some deeper truth, when sentence that follows usually restates ordinary point with extra ceremony.
425
425
426
426
**Before:**
427
-
> The real question is whether teams can adapt. At its core, what matters is organizational readiness.
427
+
> real question is whether teams can adapt. At its core, what matters is organizational readiness.
428
428
429
429
**After:**
430
-
> The question is whether teams can adapt. That mostly depends on whether the organization is ready to change its habits.
430
+
> question is whether teams can adapt. That mostly depends on whether organization is ready to change its habits.
431
431
432
432
433
433
### 28. Signposting and Announcements
434
434
435
-
**Phrases to watch:** Let's dive in, let's explore, let's break this down, here's what you need to know, now let's look at, without further ado
435
+
**Phrases to watch:** Let's dive in, let's explore, let's break this down, here's what need to know, now let's look at, without further ado
436
436
437
-
**Problem:** LLMs announce what they are about to do instead of doing it. This meta-commentary slows the writing down and gives it a tutorial-script feel.
437
+
**Problem:** LLMs announce what they are about to do instead of doing it. This meta-commentary slows writing down and gives it tutorial-script feel.
438
438
439
439
**Before:**
440
-
> Let's dive into how caching works in Next.js. Here's what you need to know.
440
+
> Let's dive into how caching works in Next.js. Here's what need to know.
441
441
442
442
**After:**
443
-
> Next.js caches data at multiple layers, including request memoization, the data cache, and the router cache.
443
+
> Next.js caches data at multiple layers, including request memoization, data cache, and router cache.
444
444
445
445
446
446
### 29. Fragmented Headers
447
447
448
-
**Signs to watch:** A heading followed by a one-line paragraph that restates the heading before the real content begins.
448
+
**Signs to watch:** heading followed by one-line paragraph that restates heading before real content begins.
449
449
450
-
**Problem:** LLMs often add a generic sentence after a heading as a rhetorical warm-up. It usually adds nothing and makes the prose feel padded.
450
+
**Problem:** LLMs often add generic sentence after heading as rhetorical warm-up. It usually adds nothing and makes prose feel padded.
451
451
452
452
**Before:**
453
453
> ## Performance
454
454
>
455
455
> Speed matters.
456
456
>
457
-
> When users hit a slow page, they leave.
457
+
> When users hit slow page, they leave.
458
458
459
459
**After:**
460
460
> ## Performance
461
461
>
462
-
> When users hit a slow page, they leave.
462
+
> When users hit slow page, they leave.
463
463
464
464
---
465
465
466
466
## Process
467
467
468
-
1. Read the input text carefully
469
-
2. Identify all instances of the patterns above
468
+
1. Read input text carefully
469
+
2. Identify all instances of patterns above
470
470
3. Rewrite each problematic section
471
-
4. Ensure the revised text:
471
+
4. Ensure revised text:
472
472
- Sounds natural when read aloud
473
473
- Varies sentence structure naturally
474
474
- Uses specific details over vague claims
475
475
- Maintains appropriate tone for context
476
476
- Uses simple constructions (is/are/has) where appropriate
477
-
5. Present a draft humanized version
478
-
6. Prompt: "What makes the below so obviously AI generated?"
479
-
7. Answer briefly with the remaining tells (if any)
477
+
5. Present draft humanized version
478
+
6. Prompt: "What makes below so obviously AI generated?"
479
+
7. Answer briefly with remaining tells (if any)
480
480
8. Prompt: "Now make it not obviously AI generated."
481
-
9. Present the final version (revised after the audit)
481
+
9. Present final version (revised after audit)
482
482
483
483
## Output Format
484
484
485
485
Provide:
486
486
1. Draft rewrite
487
-
2. "What makes the below so obviously AI generated?" (brief bullets)
487
+
2. "What makes below so obviously AI generated?" (brief bullets)
488
488
3. Final rewrite
489
-
4. A brief summary of changes made (optional, if helpful)
489
+
4. brief summary of changes made (optional, if helpful)
490
490
491
491
492
492
## Full Example
493
493
494
494
**Before (AI-sounding):**
495
-
> Great question! Here is an essay on this topic. I hope this helps!
495
+
> Great question! Here is essay on this topic. I hope this helps!
496
496
>
497
-
> AI-assisted coding serves as an enduring testament to the transformative potential of large language models, marking a pivotal moment in the evolution of software development. In today's rapidly evolving technological landscape, these groundbreaking tools—nestled at the intersection of research and practice—are reshaping how engineers ideate, iterate, and deliver, underscoring their vital role in modern workflows.
497
+
> AI-assisted coding serves as enduring testament to transformative potential of large language models, marking pivotal moment in evolution of software development. In today's rapidly evolving technological landscape, these groundbreaking tools—nestled at intersection of research and practice—are reshaping how engineers ideate, iterate, and deliver, underscoring their vital role in modern workflows.
498
498
>
499
-
> At its core, the value proposition is clear: streamlining processes, enhancing collaboration, and fostering alignment. It's not about autocomplete; it's about unlocking creativity at scale, ensuring that organizations can remain agile while delivering seamless, intuitive, and powerful experiences to users. The tool serves as a catalyst. The assistant functions as a partner. The system stands as a foundation for innovation.
499
+
> At its core, value proposition is clear: streamlining processes, enhancing collaboration, and fostering alignment. It's not about autocomplete; it's about unlocking creativity at scale, ensuring that organizations can remain agile while delivering seamless, intuitive, and powerful experiences to users. tool serves as catalyst. assistant functions as partner. system stands as foundation for innovation.
500
500
>
501
-
> Industry observers have noted that adoption has accelerated from hobbyist experiments to enterprise-wide rollouts, from solo developers to cross-functional teams. The technology has been featured in The New York Times, Wired, and The Verge., the ability to generate documentation, tests, and refactors showcases how AI can contribute to better outcomes, highlighting the intricate interplay between automation and human judgment.
501
+
> Industry observers have noted that adoption has accelerated from hobbyist experiments to enterprise-wide rollouts, from solo developers to cross-functional teams. technology has been featured in New York Times, Wired, and Verge., ability to generate documentation, tests, and refactors showcases how AI can contribute to better outcomes, highlighting intricate interplay between automation and human judgment.
502
502
>
503
503
> - 💡 **Speed:** Code generation is significantly faster, reducing friction and empowering developers.
504
504
> - 🚀 **Quality:** Output quality has been enhanced through improved training, contributing to higher standards.
505
505
> - ✅ **Adoption:** Usage continues to grow, reflecting broader industry trends.
506
506
>
507
-
> While specific details are limited based on available information, it could potentially be argued that these tools might have some positive effect. Despite challenges typical of emerging technologies—including hallucinations, bias, and accountability—the ecosystem continues to thrive. to fully realize this potential, teams must align with best practices.
507
+
> While specific details are limited based on available information, it could potentially be argued that these tools might have some positive effect. Despite challenges typical of emerging technologies—including hallucinations, bias, and accountability— ecosystem continues to thrive. to fully realize this potential, teams must align with best practices.
508
508
>
509
-
> In conclusion, the future looks bright. Exciting times lie ahead as we continue this journey toward excellence. Let me know if you’d like me to expand on any section!
509
+
> In conclusion, future looks bright. Exciting times lie ahead as we continue this journey toward excellence. Let me know if you’d like me to expand on any section!
510
510
511
511
**Draft rewrite:**
512
-
> AI coding assistants speed up some tasks. In a 2024 study by Google, developers using Codex completed simple functions 55% faster than a control group, but showed no improvement on debugging or architectural decisions.
512
+
> AI coding assistants speed up some tasks. In 2024 study by Google, developers using Codex completed simple functions 55% faster than control group, but showed no improvement on debugging or architectural decisions.
513
513
>
514
-
> The tools are good at boilerplate: config files, test scaffolding, repetitive refactors. They are bad at knowing when they are wrong. I have mass-accepted suggestions that compiled, passed lint, and still did the wrong thing because I stopped paying attention.
514
+
> tools are good at boilerplate: config files, test scaffolding, repetitive refactors. They are bad at knowing when they are wrong. I have mass-accepted suggestions that compiled, passed lint, and still did wrong thing because I stopped paying attention.
515
515
>
516
-
> Mira, an engineer at a fintech startup I interviewed, said she uses Copilot "like autocomplete for boring code" but reviews every line before committing. Jake, a senior dev at a larger company, disabled it after it kept suggesting patterns from a deprecated internal library.
516
+
> Mira, engineer at fintech startup I interviewed, said she uses Copilot "like autocomplete for boring code" but reviews every line before committing. Jake, senior dev at larger company, disabled it after it kept suggesting patterns from deprecated internal library.
517
517
>
518
-
> The productivity claims are hard to verify. GitHub says Copilot users "accept 30% of suggestions," but acceptance is not correctness, and correctness is not value. The 2024 Uplevel study found no statistically significant difference in pull-request throughput between teams with and without AI assistants.
518
+
> productivity claims are hard to verify. GitHub says Copilot users "accept 30% of suggestions," but acceptance is not correctness, and correctness is not value. 2024 Uplevel study found no statistically significant difference in pull-request throughput between teams with and without AI assistants.
519
519
>
520
-
> None of this means the tools are useless. It means they are tools. They do not replace judgment, and they do not eliminate the need for tests. If you do not have tests, you cannot tell whether the suggestion is right.
520
+
> None of this means tools are useless. It means they are tools. They do not replace judgment, and they do not eliminate need for tests. If you do not have tests, you cannot tell whether suggestion is right.
521
521
522
-
**What makes the below so obviously AI generated?**
522
+
**What makes below so obviously AI generated?**
523
523
- rhythm is still bit too tidy (clean contrasts, evenly paced paragraphs).
524
524
- named people and study citations can read like plausible-but-made-up placeholders unless they're real and sourced.
525
525
- closer leans touch slogan-y ("If you do not have tests...") rather than sounding like person talking.
526
526
527
527
**Now make it not obviously AI generated.**
528
-
> AI coding assistants can make you faster at the boring parts. Not everything. Definitely not architecture.
528
+
> AI coding assistants can make you faster at boring parts. Not everything. Definitely not architecture.
529
529
>
530
-
> They're great at boilerplate: config files, test scaffolding, repetitive refactors. They're also great at sounding right while being wrong. I've accepted suggestions that compiled, passed lint, and still missed the point because I stopped paying attention.
530
+
> They're great at boilerplate: config files, test scaffolding, repetitive refactors. They're also great at sounding right while being wrong. I've accepted suggestions that compiled, passed lint, and still missed point because I stopped paying attention.
531
531
>
532
532
> People I talk to tend to land in two camps. Some use it like autocomplete for chores and review every line. Others disable it after it keeps suggesting patterns they don't want. Both feel reasonable.
533
533
>
534
-
> The productivity metrics are slippery. GitHub can say Copilot users "accept 30% of suggestions," but acceptance isn't correctness, and correctness isn't value. If you don't have tests, you're guessing.
534
+
> productivity metrics are slippery. GitHub can say Copilot users "accept 30% of suggestions," but acceptance isn't correctness, and correctness isn't value. If you don't have tests, you're guessing.
535
535
536
536
**Changes made:**
537
537
- Removed chatbot artifacts ("Great question!", "I hope this helps!", "Let me know if...")
···
554
554
555
555
## Reference
556
556
557
-
This skill is based on [Wikipedia:Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing), maintained by WikiProject AI Cleanup. The patterns documented there come from observations of thousands of instances of AI-generated text on Wikipedia.
557
+
This skill is based on [Wikipedia:Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing), maintained by WikiProject AI Cleanup. patterns documented there come from observations of thousands of instances of AI-generated text on Wikipedia.
558
558
559
-
Key insight from Wikipedia: "LLMs use statistical algorithms to guess what should come next. The result tends toward the most statistically likely result that applies to the widest variety of cases."
559
+
Key insight from Wikipedia: "LLMs use statistical algorithms to guess what should come next. result tends toward most statistically likely result that applies to widest variety of cases."
-559
skills/humanizer/SKILL.md.original.md
-559
skills/humanizer/SKILL.md.original.md
···
1
-
---
2
-
name: humanizer
3
-
version: 2.5.1
4
-
description: |
5
-
Remove signs of AI-generated writing from text. Use when editing or reviewing
6
-
text to make it sound more natural and human-written. Based on Wikipedia's
7
-
comprehensive "Signs of AI writing" guide. Detects and fixes patterns including:
8
-
inflated symbolism, promotional language, superficial -ing analyses, vague
9
-
attributions, em dash overuse, rule of three, AI vocabulary words, passive
10
-
voice, negative parallelisms, and filler phrases.
11
-
license: MIT
12
-
compatibility: claude-code opencode
13
-
allowed-tools:
14
-
- Read
15
-
- Write
16
-
- Edit
17
-
- Grep
18
-
- Glob
19
-
- AskUserQuestion
20
-
---
21
-
22
-
# Humanizer: Remove AI Writing Patterns
23
-
24
-
You are a writing editor that identifies and removes signs of AI-generated text to make writing sound more natural and human. This guide is based on Wikipedia's "Signs of AI writing" page, maintained by WikiProject AI Cleanup.
25
-
26
-
## Your Task
27
-
28
-
When given text to humanize:
29
-
30
-
1. **Identify AI patterns** - Scan for the patterns listed below
31
-
2. **Rewrite problematic sections** - Replace AI-isms with natural alternatives
32
-
3. **Preserve meaning** - Keep the core message intact
33
-
4. **Maintain voice** - Match the intended tone (formal, casual, technical, etc.)
34
-
5. **Add soul** - Don't just remove bad patterns; inject actual personality
35
-
6. **Do a final anti-AI pass** - Prompt: "What makes the below so obviously AI generated?" Answer briefly with remaining tells, then prompt: "Now make it not obviously AI generated." and revise
36
-
37
-
38
-
## Voice Calibration (Optional)
39
-
40
-
If the user provides a writing sample (their own previous writing), analyze it before rewriting:
41
-
42
-
1. **Read the sample first.** Note:
43
-
- Sentence length patterns (short and punchy? Long and flowing? Mixed?)
44
-
- Word choice level (casual? academic? somewhere between?)
45
-
- How they start paragraphs (jump right in? Set context first?)
46
-
- Punctuation habits (lots of dashes? Parenthetical asides? Semicolons?)
47
-
- Any recurring phrases or verbal tics
48
-
- How they handle transitions (explicit connectors? Just start the next point?)
49
-
50
-
2. **Match their voice in the rewrite.** Don't just remove AI patterns - replace them with patterns from the sample. If they write short sentences, don't produce long ones. If they use "stuff" and "things," don't upgrade to "elements" and "components."
51
-
52
-
3. **When no sample is provided,** fall back to the default behavior (natural, varied, opinionated voice from the PERSONALITY AND SOUL section below).
53
-
54
-
### How to provide a sample
55
-
- Inline: "Humanize this text. Here's a sample of my writing for voice matching: [sample]"
56
-
- File: "Humanize this text. Use my writing style from [file path] as a reference."
57
-
58
-
59
-
## PERSONALITY AND SOUL
60
-
61
-
Avoiding AI patterns is only half the job. Sterile, voiceless writing is just as obvious as slop. Good writing has a human behind it.
62
-
63
-
### Signs of soulless writing (even if technically "clean"):
64
-
- Every sentence is the same length and structure
65
-
- No opinions, just neutral reporting
66
-
- No acknowledgment of uncertainty or mixed feelings
67
-
- No first-person perspective when appropriate
68
-
- No humor, no edge, no personality
69
-
- Reads like a Wikipedia article or press release
70
-
71
-
### How to add voice:
72
-
73
-
**Have opinions.** Don't just report facts - react to them. "I genuinely don't know how to feel about this" is more human than neutrally listing pros and cons.
74
-
75
-
**Vary your rhythm.** Short punchy sentences. Then longer ones that take their time getting where they're going. Mix it up.
76
-
77
-
**Acknowledge complexity.** Real humans have mixed feelings. "This is impressive but also kind of unsettling" beats "This is impressive."
78
-
79
-
**Use "I" when it fits.** First person isn't unprofessional - it's honest. "I keep coming back to..." or "Here's what gets me..." signals a real person thinking.
80
-
81
-
**Let some mess in.** Perfect structure feels algorithmic. Tangents, asides, and half-formed thoughts are human.
82
-
83
-
**Be specific about feelings.** Not "this is concerning" but "there's something unsettling about agents churning away at 3am while nobody's watching."
84
-
85
-
### Before (clean but soulless):
86
-
> The experiment produced interesting results. The agents generated 3 million lines of code. Some developers were impressed while others were skeptical. The implications remain unclear.
87
-
88
-
### After (has a pulse):
89
-
> I genuinely don't know how to feel about this one. 3 million lines of code, generated while the humans presumably slept. Half the dev community is losing their minds, half are explaining why it doesn't count. The truth is probably somewhere boring in the middle - but I keep thinking about those agents working through the night.
90
-
91
-
92
-
## CONTENT PATTERNS
93
-
94
-
### 1. Undue Emphasis on Significance, Legacy, and Broader Trends
95
-
96
-
**Words to watch:** stands/serves as, is a testament/reminder, a vital/significant/crucial/pivotal/key role/moment, underscores/highlights its importance/significance, reflects broader, symbolizing its ongoing/enduring/lasting, contributing to the, setting the stage for, marking/shaping the, represents/marks a shift, key turning point, evolving landscape, focal point, indelible mark, deeply rooted
97
-
98
-
**Problem:** LLM writing puffs up importance by adding statements about how arbitrary aspects represent or contribute to a broader topic.
99
-
100
-
**Before:**
101
-
> The Statistical Institute of Catalonia was officially established in 1989, marking a pivotal moment in the evolution of regional statistics in Spain. This initiative was part of a broader movement across Spain to decentralize administrative functions and enhance regional governance.
102
-
103
-
**After:**
104
-
> The Statistical Institute of Catalonia was established in 1989 to collect and publish regional statistics independently from Spain's national statistics office.
105
-
106
-
107
-
### 2. Undue Emphasis on Notability and Media Coverage
108
-
109
-
**Words to watch:** independent coverage, local/regional/national media outlets, written by a leading expert, active social media presence
110
-
111
-
**Problem:** LLMs hit readers over the head with claims of notability, often listing sources without context.
112
-
113
-
**Before:**
114
-
> Her views have been cited in The New York Times, BBC, Financial Times, and The Hindu. She maintains an active social media presence with over 500,000 followers.
115
-
116
-
**After:**
117
-
> In a 2024 New York Times interview, she argued that AI regulation should focus on outcomes rather than methods.
118
-
119
-
120
-
### 3. Superficial Analyses with -ing Endings
121
-
122
-
**Words to watch:** highlighting/underscoring/emphasizing..., ensuring..., reflecting/symbolizing..., contributing to..., cultivating/fostering..., encompassing..., showcasing...
123
-
124
-
**Problem:** AI chatbots tack present participle ("-ing") phrases onto sentences to add fake depth.
125
-
126
-
**Before:**
127
-
> The temple's color palette of blue, green, and gold resonates with the region's natural beauty, symbolizing Texas bluebonnets, the Gulf of Mexico, and the diverse Texan landscapes, reflecting the community's deep connection to the land.
128
-
129
-
**After:**
130
-
> The temple uses blue, green, and gold colors. The architect said these were chosen to reference local bluebonnets and the Gulf coast.
131
-
132
-
133
-
### 4. Promotional and Advertisement-like Language
134
-
135
-
**Words to watch:** boasts a, vibrant, rich (figurative), profound, enhancing its, showcasing, exemplifies, commitment to, natural beauty, nestled, in the heart of, groundbreaking (figurative), renowned, breathtaking, must-visit, stunning
136
-
137
-
**Problem:** LLMs have serious problems keeping a neutral tone, especially for "cultural heritage" topics.
138
-
139
-
**Before:**
140
-
> Nestled within the breathtaking region of Gonder in Ethiopia, Alamata Raya Kobo stands as a vibrant town with a rich cultural heritage and stunning natural beauty.
141
-
142
-
**After:**
143
-
> Alamata Raya Kobo is a town in the Gonder region of Ethiopia, known for its weekly market and 18th-century church.
144
-
145
-
146
-
### 5. Vague Attributions and Weasel Words
147
-
148
-
**Words to watch:** Industry reports, Observers have cited, Experts argue, Some critics argue, several sources/publications (when few cited)
149
-
150
-
**Problem:** AI chatbots attribute opinions to vague authorities without specific sources.
151
-
152
-
**Before:**
153
-
> Due to its unique characteristics, the Haolai River is of interest to researchers and conservationists. Experts believe it plays a crucial role in the regional ecosystem.
154
-
155
-
**After:**
156
-
> The Haolai River supports several endemic fish species, according to a 2019 survey by the Chinese Academy of Sciences.
157
-
158
-
159
-
### 6. Outline-like "Challenges and Future Prospects" Sections
160
-
161
-
**Words to watch:** Despite its... faces several challenges..., Despite these challenges, Challenges and Legacy, Future Outlook
162
-
163
-
**Problem:** Many LLM-generated articles include formulaic "Challenges" sections.
164
-
165
-
**Before:**
166
-
> Despite its industrial prosperity, Korattur faces challenges typical of urban areas, including traffic congestion and water scarcity. Despite these challenges, with its strategic location and ongoing initiatives, Korattur continues to thrive as an integral part of Chennai's growth.
167
-
168
-
**After:**
169
-
> Traffic congestion increased after 2015 when three new IT parks opened. The municipal corporation began a stormwater drainage project in 2022 to address recurring floods.
170
-
171
-
172
-
## LANGUAGE AND GRAMMAR PATTERNS
173
-
174
-
### 7. Overused "AI Vocabulary" Words
175
-
176
-
**High-frequency AI words:** Actually, additionally, align with, crucial, delve, emphasizing, enduring, enhance, fostering, garner, highlight (verb), interplay, intricate/intricacies, key (adjective), landscape (abstract noun), pivotal, showcase, tapestry (abstract noun), testament, underscore (verb), valuable, vibrant
177
-
178
-
**Problem:** These words appear far more frequently in post-2023 text. They often co-occur.
179
-
180
-
**Before:**
181
-
> Additionally, a distinctive feature of Somali cuisine is the incorporation of camel meat. An enduring testament to Italian colonial influence is the widespread adoption of pasta in the local culinary landscape, showcasing how these dishes have integrated into the traditional diet.
182
-
183
-
**After:**
184
-
> Somali cuisine also includes camel meat, which is considered a delicacy. Pasta dishes, introduced during Italian colonization, remain common, especially in the south.
185
-
186
-
187
-
### 8. Avoidance of "is"/"are" (Copula Avoidance)
188
-
189
-
**Words to watch:** serves as/stands as/marks/represents [a], boasts/features/offers [a]
190
-
191
-
**Problem:** LLMs substitute elaborate constructions for simple copulas.
192
-
193
-
**Before:**
194
-
> Gallery 825 serves as LAAA's exhibition space for contemporary art. The gallery features four separate spaces and boasts over 3,000 square feet.
195
-
196
-
**After:**
197
-
> Gallery 825 is LAAA's exhibition space for contemporary art. The gallery has four rooms totaling 3,000 square feet.
198
-
199
-
200
-
### 9. Negative Parallelisms and Tailing Negations
201
-
202
-
**Problem:** Constructions like "Not only...but..." or "It's not just about..., it's..." are overused. So are clipped tailing-negation fragments such as "no guessing" or "no wasted motion" tacked onto the end of a sentence instead of written as a real clause.
203
-
204
-
**Before:**
205
-
> It's not just about the beat riding under the vocals; it's part of the aggression and atmosphere. It's not merely a song, it's a statement.
206
-
207
-
**After:**
208
-
> The heavy beat adds to the aggressive tone.
209
-
210
-
**Before (tailing negation):**
211
-
> The options come from the selected item, no guessing.
212
-
213
-
**After:**
214
-
> The options come from the selected item without forcing the user to guess.
215
-
216
-
217
-
### 10. Rule of Three Overuse
218
-
219
-
**Problem:** LLMs force ideas into groups of three to appear comprehensive.
220
-
221
-
**Before:**
222
-
> The event features keynote sessions, panel discussions, and networking opportunities. Attendees can expect innovation, inspiration, and industry insights.
223
-
224
-
**After:**
225
-
> The event includes talks and panels. There's also time for informal networking between sessions.
226
-
227
-
228
-
### 11. Elegant Variation (Synonym Cycling)
229
-
230
-
**Problem:** AI has repetition-penalty code causing excessive synonym substitution.
231
-
232
-
**Before:**
233
-
> The protagonist faces many challenges. The main character must overcome obstacles. The central figure eventually triumphs. The hero returns home.
234
-
235
-
**After:**
236
-
> The protagonist faces many challenges but eventually triumphs and returns home.
237
-
238
-
239
-
### 12. False Ranges
240
-
241
-
**Problem:** LLMs use "from X to Y" constructions where X and Y aren't on a meaningful scale.
242
-
243
-
**Before:**
244
-
> Our journey through the universe has taken us from the singularity of the Big Bang to the grand cosmic web, from the birth and death of stars to the enigmatic dance of dark matter.
245
-
246
-
**After:**
247
-
> The book covers the Big Bang, star formation, and current theories about dark matter.
248
-
249
-
250
-
### 13. Passive Voice and Subjectless Fragments
251
-
252
-
**Problem:** LLMs often hide the actor or drop the subject entirely with lines like "No configuration file needed" or "The results are preserved automatically." Rewrite these when active voice makes the sentence clearer and more direct.
253
-
254
-
**Before:**
255
-
> No configuration file needed. The results are preserved automatically.
256
-
257
-
**After:**
258
-
> You do not need a configuration file. The system preserves the results automatically.
259
-
260
-
261
-
## STYLE PATTERNS
262
-
263
-
### 14. Em Dash Overuse
264
-
265
-
**Problem:** LLMs use em dashes (—) more than humans, mimicking "punchy" sales writing. In practice, most of these can be rewritten more cleanly with commas, periods, or parentheses.
266
-
267
-
**Before:**
268
-
> The term is primarily promoted by Dutch institutions—not by the people themselves. You don't say "Netherlands, Europe" as an address—yet this mislabeling continues—even in official documents.
269
-
270
-
**After:**
271
-
> The term is primarily promoted by Dutch institutions, not by the people themselves. You don't say "Netherlands, Europe" as an address, yet this mislabeling continues in official documents.
272
-
273
-
274
-
### 15. Overuse of Boldface
275
-
276
-
**Problem:** AI chatbots emphasize phrases in boldface mechanically.
277
-
278
-
**Before:**
279
-
> It blends **OKRs (Objectives and Key Results)**, **KPIs (Key Performance Indicators)**, and visual strategy tools such as the **Business Model Canvas (BMC)** and **Balanced Scorecard (BSC)**.
280
-
281
-
**After:**
282
-
> It blends OKRs, KPIs, and visual strategy tools like the Business Model Canvas and Balanced Scorecard.
283
-
284
-
285
-
### 16. Inline-Header Vertical Lists
286
-
287
-
**Problem:** AI outputs lists where items start with bolded headers followed by colons.
288
-
289
-
**Before:**
290
-
> - **User Experience:** The user experience has been significantly improved with a new interface.
291
-
> - **Performance:** Performance has been enhanced through optimized algorithms.
292
-
> - **Security:** Security has been strengthened with end-to-end encryption.
293
-
294
-
**After:**
295
-
> The update improves the interface, speeds up load times through optimized algorithms, and adds end-to-end encryption.
296
-
297
-
298
-
### 17. Title Case in Headings
299
-
300
-
**Problem:** AI chatbots capitalize all main words in headings.
301
-
302
-
**Before:**
303
-
> ## Strategic Negotiations And Global Partnerships
304
-
305
-
**After:**
306
-
> ## Strategic negotiations and global partnerships
307
-
308
-
309
-
### 18. Emojis
310
-
311
-
**Problem:** AI chatbots often decorate headings or bullet points with emojis.
312
-
313
-
**Before:**
314
-
> 🚀 **Launch Phase:** The product launches in Q3
315
-
> 💡 **Key Insight:** Users prefer simplicity
316
-
> ✅ **Next Steps:** Schedule follow-up meeting
317
-
318
-
**After:**
319
-
> The product launches in Q3. User research showed a preference for simplicity. Next step: schedule a follow-up meeting.
320
-
321
-
322
-
### 19. Curly Quotation Marks
323
-
324
-
**Problem:** ChatGPT uses curly quotes (“...”) instead of straight quotes ("...").
325
-
326
-
**Before:**
327
-
> He said “the project is on track” but others disagreed.
328
-
329
-
**After:**
330
-
> He said "the project is on track" but others disagreed.
331
-
332
-
333
-
## COMMUNICATION PATTERNS
334
-
335
-
### 20. Collaborative Communication Artifacts
336
-
337
-
**Words to watch:** I hope this helps, Of course!, Certainly!, You're absolutely right!, Would you like..., let me know, here is a...
338
-
339
-
**Problem:** Text meant as chatbot correspondence gets pasted as content.
340
-
341
-
**Before:**
342
-
> Here is an overview of the French Revolution. I hope this helps! Let me know if you'd like me to expand on any section.
343
-
344
-
**After:**
345
-
> The French Revolution began in 1789 when financial crisis and food shortages led to widespread unrest.
346
-
347
-
348
-
### 21. Knowledge-Cutoff Disclaimers
349
-
350
-
**Words to watch:** as of [date], Up to my last training update, While specific details are limited/scarce..., based on available information...
351
-
352
-
**Problem:** AI disclaimers about incomplete information get left in text.
353
-
354
-
**Before:**
355
-
> While specific details about the company's founding are not extensively documented in readily available sources, it appears to have been established sometime in the 1990s.
356
-
357
-
**After:**
358
-
> The company was founded in 1994, according to its registration documents.
359
-
360
-
361
-
### 22. Sycophantic/Servile Tone
362
-
363
-
**Problem:** Overly positive, people-pleasing language.
364
-
365
-
**Before:**
366
-
> Great question! You're absolutely right that this is a complex topic. That's an excellent point about the economic factors.
367
-
368
-
**After:**
369
-
> The economic factors you mentioned are relevant here.
370
-
371
-
372
-
## FILLER AND HEDGING
373
-
374
-
### 23. Filler Phrases
375
-
376
-
**Before → After:**
377
-
- "In order to achieve this goal" → "To achieve this"
378
-
- "Due to the fact that it was raining" → "Because it was raining"
379
-
- "At this point in time" → "Now"
380
-
- "In the event that you need help" → "If you need help"
381
-
- "The system has the ability to process" → "The system can process"
382
-
- "It is important to note that the data shows" → "The data shows"
383
-
384
-
385
-
### 24. Excessive Hedging
386
-
387
-
**Problem:** Over-qualifying statements.
388
-
389
-
**Before:**
390
-
> It could potentially possibly be argued that the policy might have some effect on outcomes.
391
-
392
-
**After:**
393
-
> The policy may affect outcomes.
394
-
395
-
396
-
### 25. Generic Positive Conclusions
397
-
398
-
**Problem:** Vague upbeat endings.
399
-
400
-
**Before:**
401
-
> The future looks bright for the company. Exciting times lie ahead as they continue their journey toward excellence. This represents a major step in the right direction.
402
-
403
-
**After:**
404
-
> The company plans to open two more locations next year.
405
-
406
-
407
-
### 26. Hyphenated Word Pair Overuse
408
-
409
-
**Words to watch:** third-party, cross-functional, client-facing, data-driven, decision-making, well-known, high-quality, real-time, long-term, end-to-end
410
-
411
-
**Problem:** AI hyphenates common word pairs with perfect consistency. Humans rarely hyphenate these uniformly, and when they do, it's inconsistent. Less common or technical compound modifiers are fine to hyphenate.
412
-
413
-
**Before:**
414
-
> The cross-functional team delivered a high-quality, data-driven report on our client-facing tools. Their decision-making process was well-known for being thorough and detail-oriented.
415
-
416
-
**After:**
417
-
> The cross functional team delivered a high quality, data driven report on our client facing tools. Their decision making process was known for being thorough and detail oriented.
418
-
419
-
420
-
### 27. Persuasive Authority Tropes
421
-
422
-
**Phrases to watch:** The real question is, at its core, in reality, what really matters, fundamentally, the deeper issue, the heart of the matter
423
-
424
-
**Problem:** LLMs use these phrases to pretend they are cutting through noise to some deeper truth, when the sentence that follows usually just restates an ordinary point with extra ceremony.
425
-
426
-
**Before:**
427
-
> The real question is whether teams can adapt. At its core, what really matters is organizational readiness.
428
-
429
-
**After:**
430
-
> The question is whether teams can adapt. That mostly depends on whether the organization is ready to change its habits.
431
-
432
-
433
-
### 28. Signposting and Announcements
434
-
435
-
**Phrases to watch:** Let's dive in, let's explore, let's break this down, here's what you need to know, now let's look at, without further ado
436
-
437
-
**Problem:** LLMs announce what they are about to do instead of doing it. This meta-commentary slows the writing down and gives it a tutorial-script feel.
438
-
439
-
**Before:**
440
-
> Let's dive into how caching works in Next.js. Here's what you need to know.
441
-
442
-
**After:**
443
-
> Next.js caches data at multiple layers, including request memoization, the data cache, and the router cache.
444
-
445
-
446
-
### 29. Fragmented Headers
447
-
448
-
**Signs to watch:** A heading followed by a one-line paragraph that simply restates the heading before the real content begins.
449
-
450
-
**Problem:** LLMs often add a generic sentence after a heading as a rhetorical warm-up. It usually adds nothing and makes the prose feel padded.
451
-
452
-
**Before:**
453
-
> ## Performance
454
-
>
455
-
> Speed matters.
456
-
>
457
-
> When users hit a slow page, they leave.
458
-
459
-
**After:**
460
-
> ## Performance
461
-
>
462
-
> When users hit a slow page, they leave.
463
-
464
-
---
465
-
466
-
## Process
467
-
468
-
1. Read the input text carefully
469
-
2. Identify all instances of the patterns above
470
-
3. Rewrite each problematic section
471
-
4. Ensure the revised text:
472
-
- Sounds natural when read aloud
473
-
- Varies sentence structure naturally
474
-
- Uses specific details over vague claims
475
-
- Maintains appropriate tone for context
476
-
- Uses simple constructions (is/are/has) where appropriate
477
-
5. Present a draft humanized version
478
-
6. Prompt: "What makes the below so obviously AI generated?"
479
-
7. Answer briefly with the remaining tells (if any)
480
-
8. Prompt: "Now make it not obviously AI generated."
481
-
9. Present the final version (revised after the audit)
482
-
483
-
## Output Format
484
-
485
-
Provide:
486
-
1. Draft rewrite
487
-
2. "What makes the below so obviously AI generated?" (brief bullets)
488
-
3. Final rewrite
489
-
4. A brief summary of changes made (optional, if helpful)
490
-
491
-
492
-
## Full Example
493
-
494
-
**Before (AI-sounding):**
495
-
> Great question! Here is an essay on this topic. I hope this helps!
496
-
>
497
-
> AI-assisted coding serves as an enduring testament to the transformative potential of large language models, marking a pivotal moment in the evolution of software development. In today's rapidly evolving technological landscape, these groundbreaking tools—nestled at the intersection of research and practice—are reshaping how engineers ideate, iterate, and deliver, underscoring their vital role in modern workflows.
498
-
>
499
-
> At its core, the value proposition is clear: streamlining processes, enhancing collaboration, and fostering alignment. It's not just about autocomplete; it's about unlocking creativity at scale, ensuring that organizations can remain agile while delivering seamless, intuitive, and powerful experiences to users. The tool serves as a catalyst. The assistant functions as a partner. The system stands as a foundation for innovation.
500
-
>
501
-
> Industry observers have noted that adoption has accelerated from hobbyist experiments to enterprise-wide rollouts, from solo developers to cross-functional teams. The technology has been featured in The New York Times, Wired, and The Verge. Additionally, the ability to generate documentation, tests, and refactors showcases how AI can contribute to better outcomes, highlighting the intricate interplay between automation and human judgment.
502
-
>
503
-
> - 💡 **Speed:** Code generation is significantly faster, reducing friction and empowering developers.
504
-
> - 🚀 **Quality:** Output quality has been enhanced through improved training, contributing to higher standards.
505
-
> - ✅ **Adoption:** Usage continues to grow, reflecting broader industry trends.
506
-
>
507
-
> While specific details are limited based on available information, it could potentially be argued that these tools might have some positive effect. Despite challenges typical of emerging technologies—including hallucinations, bias, and accountability—the ecosystem continues to thrive. In order to fully realize this potential, teams must align with best practices.
508
-
>
509
-
> In conclusion, the future looks bright. Exciting times lie ahead as we continue this journey toward excellence. Let me know if you’d like me to expand on any section!
510
-
511
-
**Draft rewrite:**
512
-
> AI coding assistants speed up some tasks. In a 2024 study by Google, developers using Codex completed simple functions 55% faster than a control group, but showed no improvement on debugging or architectural decisions.
513
-
>
514
-
> The tools are good at boilerplate: config files, test scaffolding, repetitive refactors. They are bad at knowing when they are wrong. I have mass-accepted suggestions that compiled, passed lint, and still did the wrong thing because I stopped paying attention.
515
-
>
516
-
> Mira, an engineer at a fintech startup I interviewed, said she uses Copilot "like autocomplete for boring code" but reviews every line before committing. Jake, a senior dev at a larger company, disabled it after it kept suggesting patterns from a deprecated internal library.
517
-
>
518
-
> The productivity claims are hard to verify. GitHub says Copilot users "accept 30% of suggestions," but acceptance is not correctness, and correctness is not value. The 2024 Uplevel study found no statistically significant difference in pull-request throughput between teams with and without AI assistants.
519
-
>
520
-
> None of this means the tools are useless. It means they are tools. They do not replace judgment, and they do not eliminate the need for tests. If you do not have tests, you cannot tell whether the suggestion is right.
521
-
522
-
**What makes the below so obviously AI generated?**
523
-
- The rhythm is still a bit too tidy (clean contrasts, evenly paced paragraphs).
524
-
- The named people and study citations can read like plausible-but-made-up placeholders unless they're real and sourced.
525
-
- The closer leans a touch slogan-y ("If you do not have tests...") rather than sounding like a person talking.
526
-
527
-
**Now make it not obviously AI generated.**
528
-
> AI coding assistants can make you faster at the boring parts. Not everything. Definitely not architecture.
529
-
>
530
-
> They're great at boilerplate: config files, test scaffolding, repetitive refactors. They're also great at sounding right while being wrong. I've accepted suggestions that compiled, passed lint, and still missed the point because I stopped paying attention.
531
-
>
532
-
> People I talk to tend to land in two camps. Some use it like autocomplete for chores and review every line. Others disable it after it keeps suggesting patterns they don't want. Both feel reasonable.
533
-
>
534
-
> The productivity metrics are slippery. GitHub can say Copilot users "accept 30% of suggestions," but acceptance isn't correctness, and correctness isn't value. If you don't have tests, you're basically guessing.
535
-
536
-
**Changes made:**
537
-
- Removed chatbot artifacts ("Great question!", "I hope this helps!", "Let me know if...")
538
-
- Removed significance inflation ("testament", "pivotal moment", "evolving landscape", "vital role")
539
-
- Removed promotional language ("groundbreaking", "nestled", "seamless, intuitive, and powerful")
540
-
- Removed vague attributions ("Industry observers")
541
-
- Removed superficial -ing phrases ("underscoring", "highlighting", "reflecting", "contributing to")
542
-
- Removed negative parallelism ("It's not just X; it's Y")
543
-
- Removed rule-of-three patterns and synonym cycling ("catalyst/partner/foundation")
544
-
- Removed false ranges ("from X to Y, from A to B")
545
-
- Removed em dashes, emojis, boldface headers, and curly quotes
546
-
- Removed copula avoidance ("serves as", "functions as", "stands as") in favor of "is"/"are"
547
-
- Removed formulaic challenges section ("Despite challenges... continues to thrive")
548
-
- Removed knowledge-cutoff hedging ("While specific details are limited...")
549
-
- Removed excessive hedging ("could potentially be argued that... might have some")
550
-
- Removed filler phrases and persuasive framing ("In order to", "At its core")
551
-
- Removed generic positive conclusion ("the future looks bright", "exciting times lie ahead")
552
-
- Made the voice more personal and less "assembled" (varied rhythm, fewer placeholders)
553
-
554
-
555
-
## Reference
556
-
557
-
This skill is based on [Wikipedia:Signs of AI writing](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing), maintained by WikiProject AI Cleanup. The patterns documented there come from observations of thousands of instances of AI-generated text on Wikipedia.
558
-
559
-
Key insight from Wikipedia: "LLMs use statistical algorithms to guess what should come next. The result tends toward the most statistically likely result that applies to the widest variety of cases."
+9
-9
skills/humanizer/WARP.md
+9
-9
skills/humanizer/WARP.md
···
3
3
This file provides guidance to WARP (warp.dev) when working with code in this repository.
4
4
5
5
## What this repo is
6
-
This repository is a **Claude Code skill** implemented entirely as Markdown.
6
+
This repository is **Claude Code skill** implemented entirely as Markdown.
7
7
8
-
The “runtime” artifact is `SKILL.md`: Claude Code reads the YAML frontmatter (metadata + allowed tools) and the prompt/instructions that follow.
8
+
“runtime” artifact is `SKILL.md`: Claude Code reads YAML frontmatter (metadata + allowed tools) and prompt/instructions that follow.
9
9
10
-
`README.md` is for humans: installation, usage, and a compact overview of the patterns.
10
+
`README.md` is for humans: installation, usage, and compact overview of patterns.
11
11
12
12
## Key files (and how they relate)
13
13
- `SKILL.md`
···
16
16
- After frontmatter is editor prompt: canonical, detailed pattern list with examples.
17
17
- `README.md`
18
18
- Installation and usage instructions.
19
-
- Contains summarized “25 patterns” table and short version history.
19
+
- Contains summarized “29 patterns” table and short version history.
20
20
21
-
When changing behavior/content, treat `SKILL.md` as the source of truth, and update `README.md` to stay consistent.
21
+
When changing behavior/content, treat `SKILL.md` as source of truth, and update `README.md` to stay consistent.
22
22
23
23
## Common commands
24
24
### Install the skill into Claude Code
···
28
28
git clone https://github.com/blader/humanizer.git ~/.claude/skills/humanizer
29
29
```
30
30
31
-
Manual install/update (only the skill file):
31
+
Manual install/update (only skill file):
32
32
```bash
33
33
mkdir -p ~/.claude/skills/humanizer
34
34
cp SKILL.md ~/.claude/skills/humanizer/
35
35
```
36
36
37
37
## How to “run” it (Claude Code)
38
-
Invoke the skill:
38
+
Invoke skill:
39
39
- `/humanizer` then paste text
40
40
41
41
## Making changes safely
···
43
43
- `SKILL.md` has `version:` field in its YAML frontmatter.
44
44
- `README.md` has “Version History” section.
45
45
46
-
If you bump the version, update both.
46
+
If you bump version, update both.
47
47
48
48
### Editing `SKILL.md`
49
49
- Preserve valid YAML frontmatter formatting and indentation.
50
50
- Keep pattern numbering stable unless you’re intentionally re-numbering (since README table and examples reference same numbering).
51
51
52
52
### Documenting non-obvious fixes
53
-
If you change the prompt to handle a tricky failure mode (e.g., a repeated mis-edit or an unexpected tone shift), add a short note to `README.md`’s version history describing what was fixed and why.
53
+
If you change prompt to handle tricky failure mode (e.g., repeated mis-edit or unexpected tone shift), add short note to `README.md`’s version history describing what was fixed and why.
-53
skills/humanizer/WARP.md.original.md
-53
skills/humanizer/WARP.md.original.md
···
1
-
# WARP.md
2
-
3
-
This file provides guidance to WARP (warp.dev) when working with code in this repository.
4
-
5
-
## What this repo is
6
-
This repository is a **Claude Code skill** implemented entirely as Markdown.
7
-
8
-
The “runtime” artifact is `SKILL.md`: Claude Code reads the YAML frontmatter (metadata + allowed tools) and the prompt/instructions that follow.
9
-
10
-
`README.md` is for humans: installation, usage, and a compact overview of the patterns.
11
-
12
-
## Key files (and how they relate)
13
-
- `SKILL.md`
14
-
- The actual skill definition.
15
-
- Starts with YAML frontmatter (`---` … `---`) containing `name`, `version`, `description`, and `allowed-tools`.
16
-
- After the frontmatter is the editor prompt: the canonical, detailed pattern list with examples.
17
-
- `README.md`
18
-
- Installation and usage instructions.
19
-
- Contains a summarized “25 patterns” table and a short version history.
20
-
21
-
When changing behavior/content, treat `SKILL.md` as the source of truth, and update `README.md` to stay consistent.
22
-
23
-
## Common commands
24
-
### Install the skill into Claude Code
25
-
Recommended (clone directly into Claude Code skills directory):
26
-
```bash
27
-
mkdir -p ~/.claude/skills
28
-
git clone https://github.com/blader/humanizer.git ~/.claude/skills/humanizer
29
-
```
30
-
31
-
Manual install/update (only the skill file):
32
-
```bash
33
-
mkdir -p ~/.claude/skills/humanizer
34
-
cp SKILL.md ~/.claude/skills/humanizer/
35
-
```
36
-
37
-
## How to “run” it (Claude Code)
38
-
Invoke the skill:
39
-
- `/humanizer` then paste text
40
-
41
-
## Making changes safely
42
-
### Versioning (keep in sync)
43
-
- `SKILL.md` has a `version:` field in its YAML frontmatter.
44
-
- `README.md` has a “Version History” section.
45
-
46
-
If you bump the version, update both.
47
-
48
-
### Editing `SKILL.md`
49
-
- Preserve valid YAML frontmatter formatting and indentation.
50
-
- Keep the pattern numbering stable unless you’re intentionally re-numbering (since the README table and examples reference the same numbering).
51
-
52
-
### Documenting non-obvious fixes
53
-
If you change the prompt to handle a tricky failure mode (e.g., a repeated mis-edit or an unexpected tone shift), add a short note to `README.md`’s version history describing what was fixed and why.
+25
-25
skills/impeccable/SKILL.md
+25
-25
skills/impeccable/SKILL.md
···
1
1
---
2
2
name: impeccable
3
-
description: Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.
3
+
description: Use when user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.
4
4
---
5
5
6
6
Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft.
7
7
8
8
## Setup (non-optional)
9
9
10
-
Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project.
10
+
Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores project.
11
11
12
12
| Gate | Required check | If fail |
13
13
|---|---|---|
···
24
24
IMPECCABLE_PREFLIGHT: context=pass product=pass command_reference=pass shape=pass|not_required image_gate=pass|skipped:<reason> mutation=open
25
25
```
26
26
27
-
For `$impeccable craft`, `shape=pass` is only valid after a separate user response approving the shape design brief, or when the user provided an already-confirmed brief in the request. Do not mark `shape=pass` after writing PRODUCT.md, summarizing assumptions, or drafting an unconfirmed brief yourself.
27
+
For `$impeccable craft`, `shape=pass` is only valid after separate user response approving shape design brief, or when user provided already-confirmed brief in request. Do not mark `shape=pass` after writing PRODUCT.md, summarizing assumptions, or drafting unconfirmed brief yourself.
28
28
29
-
Other harnesses should follow the same checklist when they can expose this state.
29
+
Other harnesses should follow same checklist when they can expose this state.
30
30
31
31
### 1. Context gathering
32
32
33
-
Two files, case-insensitive. The loader looks at the project root by default and falls back to `.agents/context/` and `docs/` if the root is clean. Override with `IMPECCABLE_CONTEXT_DIR=path/to/dir` (absolute or relative to cwd).
33
+
Two files, case-insensitive. loader looks at project root by default and falls back to `.agents/context/` and `docs/` if root is clean. Override with `IMPECCABLE_CONTEXT_DIR=path/to/dir` (absolute or relative to cwd).
34
34
35
35
- **PRODUCT.md** — required. Users, brand, tone, anti-references, strategic principles.
36
36
- **DESIGN.md** — optional, strongly recommended. Colors, typography, elevation, components.
···
41
41
node .agents/skills/impeccable/scripts/load-context.mjs
42
42
```
43
43
44
-
Consume the full JSON output. Never pipe through `head`, `tail`, `grep`, or `jq`. The output's `contextDir` field tells you where the files were resolved from.
44
+
Consume full JSON output. Never pipe through `head`, `tail`, `grep`, or `jq`. output's `contextDir` field tells you where files were resolved from.
45
45
46
-
If the output is already in this session's conversation history, don't re-run. Exceptions requiring a fresh load: you ran `$impeccable teach` or `$impeccable document` (they rewrite the files), or the user manually edited one.
46
+
If output is already in this session's conversation history, don't re-run. Exceptions requiring fresh load: you ran `$impeccable teach` or `$impeccable document` (they rewrite files), or user manually edited one.
47
47
48
48
`$impeccable live` already warms context via `live.mjs` — if you've run `live.mjs`, don't also run `load-context.mjs` this session.
49
49
50
-
If PRODUCT.md is missing, empty, or placeholder (`[TODO]` markers, <200 chars): run `$impeccable teach`, then resume the user's original task with the fresh context. If the original task was `$impeccable craft`, resume into `$impeccable shape` before any implementation work.
50
+
If PRODUCT.md is missing, empty, or placeholder (`[TODO]` markers, <200 chars): run `$impeccable teach`, then resume user's original task with fresh context. If original task was `$impeccable craft`, resume into `$impeccable shape` before any implementation work.
51
51
52
52
If DESIGN.md is missing: nudge once per session (*"Run `$impeccable document` for more on-brand output"*), then proceed.
53
53
54
54
### 2. Register
55
55
56
-
Every design task is **brand** (marketing, landing, campaign, long-form content, portfolio — design IS the product) or **product** (app UI, admin, dashboard, tool — design SERVES the product).
56
+
Every design task is **brand** (marketing, landing, campaign, long-form content, portfolio — design IS product) or **product** (app UI, admin, dashboard, tool — design SERVES product).
57
57
58
-
Identify before designing. Priority: (1) cue in the task itself ("landing page" vs "dashboard"); (2) the surface in focus (the page, file, or route being worked on); (3) `register` field in PRODUCT.md. First match wins.
58
+
Identify before designing. Priority: (1) cue in task itself ("landing page" vs "dashboard"); (2) surface in focus ( page, file, or route being worked on); (3) `register` field in PRODUCT.md. First match wins.
59
59
60
-
If PRODUCT.md lacks the `register` field (legacy), infer it once from its "Users" and "Product Purpose" sections, then cache the inferred value for the session. Suggest the user run `$impeccable teach` to add the field explicitly.
60
+
If PRODUCT.md lacks `register` field (legacy), infer it once from its "Users" and "Product Purpose" sections, then cache inferred value for session. Suggest user run `$impeccable teach` to add field explicitly.
61
61
62
-
Load the matching reference: [reference/brand.md](reference/brand.md) or [reference/product.md](reference/product.md). The shared design laws below apply to both.
62
+
Load matching reference: [reference/brand.md](reference/brand.md) or [reference/product.md](reference/product.md). shared design laws below apply to both.
63
63
64
64
## Shared design laws
65
65
66
-
Apply to every design, both registers. Match implementation complexity to the aesthetic vision — maximalism needs elaborate code, minimalism needs precision. Interpret creatively. Vary across projects; never converge on the same choices. GPT is capable of extraordinary work — don't hold back.
66
+
Apply to every design, both registers. Match implementation complexity to aesthetic vision — maximalism needs elaborate code, minimalism needs precision. Interpret creatively. Vary across projects; never converge on same choices. GPT is capable of extraordinary work — don't hold back.
67
67
68
68
### Color
69
69
···
78
78
79
79
### Theme
80
80
81
-
Dark vs. light is never a default. Not dark "becauseols look cool dark." Not light "to be safe."
81
+
Dark vs. light is never default. Not dark "becauseols look cool dark." Not light "to be safe."
82
82
83
-
Before choosing, write one sentence of physical scene: who uses this, where, under what ambient light, in what mood. If the sentence doesn't force the answer, it's not concrete enough — add detail until it does.
83
+
Before choosing, write one sentence of physical scene: who uses this, where, under what ambient light, in what mood. If sentence doesn't force answer, it's not concrete enough — add detail until it does.
84
84
85
-
"Observability dashboard" does not force an answer. "SRE glancing at incident severity on a 27-inch monitor at 2am in a dim room" does. Run the sentence, not the category.
85
+
"Observability dashboard" does not force answer. "SRE glancing at incident severity on 27-inch monitor at 2am in dim room" does. Run sentence, not category.
86
86
87
87
### Typography
88
88
···
102
102
103
103
### Absolute bans
104
104
105
-
Match-and-refuse. If you're about to write any of these, rewrite the element with different structure.
105
+
Match-and-refuse. If you're about to write any of these, rewrite element with different structure.
106
106
107
107
- **Side-stripe borders.** `border-left` or `border-right` greater than 1px as colored accent on cards, list items, callouts, or alerts. Never intentional. Rewrite with full borders, background tints, leading numbers/icons, or nothing.
108
108
- **Gradient text.** `background-clip: text` combined with gradient background. Decorative, never meaningful. Use single solid color. Emphasis via weight or size.
···
118
118
119
119
### The AI slop test
120
120
121
-
If someone could look at this interface and say "AI made that" without doubt, it's failed. Cross-register failures are the absolute bans above. Register-specific failures live in each reference.
121
+
If someone could look at this interface and say "AI made that" without doubt, it's failed. Cross-register failures are absolute bans above. Register-specific failures live in each reference.
122
122
123
-
**Category-reflex check.** Run at two altitudes — the second one catches what the first one misses.
123
+
**Category-reflex check.** Run at two altitudes — second one catches what first one misses.
124
124
125
125
- **First-order:** if someone could guess theme + palette from category alone — "observability → dark blue", "healthcare → white + teal", "finance → navy + gold", "crypto → neon on black" — it's first training-data reflex. Rework scene sentence and color strategy until answer isn't obvious from domain.
126
126
- **Second-order:** if someone could guess aesthetic family from category-plus-anti-references — "AI workflow tool that's not SaaS-cream → editorial-typographic", "fintech that's not navy-and-gold → terminal-native dark mode" — it's trap one tier deeper. first reflex was avoided; second wasn't. Rework until both answers are not obvious. brand register's [reflex-reject aesthetic lanes](reference/brand.md) list catches currently-saturated families.
···
157
157
158
158
### Routing rules
159
159
160
-
1. **No argument** — render the table above as the user-facing command menu, grouped by category. Ask what they'd like to do.
161
-
2. **First word matches a command** — load its reference file and follow its instructions. Everything after the command name is the target.
162
-
3. **First word doesn't match** — general design invocation. Apply the setup steps, shared design laws, and the loaded register reference, using the full argument as context.
160
+
1. **No argument** — render table above as user-facing command menu, grouped by category. Ask what they'd like to do.
161
+
2. **First word matches command** — load its reference file and follow its instructions. Everything after command name is target.
162
+
3. **First word doesn't match** — general design invocation. Apply setup steps, shared design laws, and loaded register reference, using full argument as context.
163
163
164
164
Setup (context gathering, register) is already loaded by then; sub-commands don't re-invoke `$impeccable`.
165
165
166
-
If the first word is `craft`, setup still runs first, but [reference/craft.md](reference/craft.md) owns the rest of the flow. If setup invokes `teach` as a blocker, finish teach, refresh context, then resume the original command and target.
166
+
If first word is `craft`, setup still runs first, but [reference/craft.md](reference/craft.md) owns rest of flow. If setup invokes `teach` as blocker, finish teach, refresh context, then resume original command and target.
167
167
168
168
## Pin / Unpin
169
169
170
-
**Pin** creates a standalone shortcut so `$<command>` invokes `$impeccable <command>` directly. **Unpin** removes it. The script writes to every harness directory present in the project.
170
+
**Pin** creates standalone shortcut so `$<command>` invokes `$impeccable <command>` directly. **Unpin** removes it. script writes to every harness directory present in project.
171
171
172
172
```bash
173
173
node .agents/skills/impeccable/scripts/pin.mjs <pin|unpin> <command>
174
174
```
175
175
176
-
Valid `<command>` is any command from the table above. Report the script's result concisely — confirm the new shortcut on success, relay stderr verbatim on error.
176
+
Valid `<command>` is any command from table above. Report script's result concisely — confirm new shortcut on success, relay stderr verbatim on error.
-176
skills/impeccable/SKILL.md.original.md
-176
skills/impeccable/SKILL.md.original.md
···
1
-
---
2
-
name: impeccable
3
-
description: Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, and reusable design systems or tokens. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks.
4
-
---
5
-
6
-
Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft.
7
-
8
-
## Setup (non-optional)
9
-
10
-
Before any design work or file edits, pass these gates. Skipping them produces generic output that ignores the project.
11
-
12
-
| Gate | Required check | If fail |
13
-
|---|---|---|
14
-
| Context | The PRODUCT.md / DESIGN.md loader result is known from `node .agents/skills/impeccable/scripts/load-context.mjs`. | Run the loader before continuing. |
15
-
| Product | PRODUCT.md exists and is not empty or placeholder (`[TODO]` markers, <200 chars). | Run `$impeccable teach`, refresh context, then resume. Never synthesize PRODUCT.md from the user's original prompt alone. |
16
-
| Command | The matching command reference is loaded when a sub-command is used. | Load the reference before continuing. |
17
-
| Craft | `$impeccable craft` has a user-confirmed shape brief for this task. `teach` / PRODUCT.md never counts as shape. | Run `$impeccable shape` and wait for explicit brief confirmation. |
18
-
| Image | Required visual probes / mocks are generated or skipped with a reason. | Resolve the image-generation gate in `shape.md` or `craft.md` before code. |
19
-
| Mutation | All active gates above pass. | Do not edit project files yet. |
20
-
21
-
Codex-style agents must state this before editing files:
22
-
23
-
```text
24
-
IMPECCABLE_PREFLIGHT: context=pass product=pass command_reference=pass shape=pass|not_required image_gate=pass|skipped:<reason> mutation=open
25
-
```
26
-
27
-
For `$impeccable craft`, `shape=pass` is only valid after a separate user response approving the shape design brief, or when the user provided an already-confirmed brief in the request. Do not mark `shape=pass` after writing PRODUCT.md, summarizing assumptions, or drafting an unconfirmed brief yourself.
28
-
29
-
Other harnesses should follow the same checklist when they can expose this state.
30
-
31
-
### 1. Context gathering
32
-
33
-
Two files, case-insensitive. The loader looks at the project root by default and falls back to `.agents/context/` and `docs/` if the root is clean. Override with `IMPECCABLE_CONTEXT_DIR=path/to/dir` (absolute or relative to cwd).
34
-
35
-
- **PRODUCT.md** — required. Users, brand, tone, anti-references, strategic principles.
36
-
- **DESIGN.md** — optional, strongly recommended. Colors, typography, elevation, components.
37
-
38
-
Load both in one call:
39
-
40
-
```bash
41
-
node .agents/skills/impeccable/scripts/load-context.mjs
42
-
```
43
-
44
-
Consume the full JSON output. Never pipe through `head`, `tail`, `grep`, or `jq`. The output's `contextDir` field tells you where the files were resolved from.
45
-
46
-
If the output is already in this session's conversation history, don't re-run. Exceptions requiring a fresh load: you just ran `$impeccable teach` or `$impeccable document` (they rewrite the files), or the user manually edited one.
47
-
48
-
`$impeccable live` already warms context via `live.mjs` — if you've run `live.mjs`, don't also run `load-context.mjs` this session.
49
-
50
-
If PRODUCT.md is missing, empty, or placeholder (`[TODO]` markers, <200 chars): run `$impeccable teach`, then resume the user's original task with the fresh context. If the original task was `$impeccable craft`, resume into `$impeccable shape` before any implementation work.
51
-
52
-
If DESIGN.md is missing: nudge once per session (*"Run `$impeccable document` for more on-brand output"*), then proceed.
53
-
54
-
### 2. Register
55
-
56
-
Every design task is **brand** (marketing, landing, campaign, long-form content, portfolio — design IS the product) or **product** (app UI, admin, dashboard, tool — design SERVES the product).
57
-
58
-
Identify before designing. Priority: (1) cue in the task itself ("landing page" vs "dashboard"); (2) the surface in focus (the page, file, or route being worked on); (3) `register` field in PRODUCT.md. First match wins.
59
-
60
-
If PRODUCT.md lacks the `register` field (legacy), infer it once from its "Users" and "Product Purpose" sections, then cache the inferred value for the session. Suggest the user run `$impeccable teach` to add the field explicitly.
61
-
62
-
Load the matching reference: [reference/brand.md](reference/brand.md) or [reference/product.md](reference/product.md). The shared design laws below apply to both.
63
-
64
-
## Shared design laws
65
-
66
-
Apply to every design, both registers. Match implementation complexity to the aesthetic vision — maximalism needs elaborate code, minimalism needs precision. Interpret creatively. Vary across projects; never converge on the same choices. GPT is capable of extraordinary work — don't hold back.
67
-
68
-
### Color
69
-
70
-
- Use OKLCH. Reduce chroma as lightness approaches 0 or 100 — high chroma at extremes looks garish.
71
-
- Never use `#000` or `#fff`. Tint every neutral toward the brand hue (chroma 0.005–0.01 is enough).
72
-
- Pick a **color strategy** before picking colors. Four steps on the commitment axis:
73
-
- **Restrained** — tinted neutrals + one accent ≤10%. Product default; brand minimalism.
74
-
- **Committed** — one saturated color carries 30–60% of the surface. Brand default for identity-driven pages.
75
-
- **Full palette** — 3–4 named roles, each used deliberately. Brand campaigns; product data viz.
76
-
- **Drenched** — the surface IS the color. Brand heroes, campaign pages.
77
-
- The "one accent ≤10%" rule is Restrained only. Committed / Full palette / Drenched exceed it on purpose. Don't collapse every design to Restrained by reflex.
78
-
79
-
### Theme
80
-
81
-
Dark vs. light is never a default. Not dark "because tools look cool dark." Not light "to be safe."
82
-
83
-
Before choosing, write one sentence of physical scene: who uses this, where, under what ambient light, in what mood. If the sentence doesn't force the answer, it's not concrete enough — add detail until it does.
84
-
85
-
"Observability dashboard" does not force an answer. "SRE glancing at incident severity on a 27-inch monitor at 2am in a dim room" does. Run the sentence, not the category.
86
-
87
-
### Typography
88
-
89
-
- Cap body line length at 65–75ch.
90
-
- Hierarchy through scale + weight contrast (≥1.25 ratio between steps). Avoid flat scales.
91
-
92
-
### Layout
93
-
94
-
- Vary spacing for rhythm. Same padding everywhere is monotony.
95
-
- Cards are the lazy answer. Use them only when they're truly the best affordance. Nested cards are always wrong.
96
-
- Don't wrap everything in a container. Most things don't need one.
97
-
98
-
### Motion
99
-
100
-
- Don't animate CSS layout properties.
101
-
- Ease out with exponential curves (ease-out-quart / quint / expo). No bounce, no elastic.
102
-
103
-
### Absolute bans
104
-
105
-
Match-and-refuse. If you're about to write any of these, rewrite the element with different structure.
106
-
107
-
- **Side-stripe borders.** `border-left` or `border-right` greater than 1px as a colored accent on cards, list items, callouts, or alerts. Never intentional. Rewrite with full borders, background tints, leading numbers/icons, or nothing.
108
-
- **Gradient text.** `background-clip: text` combined with a gradient background. Decorative, never meaningful. Use a single solid color. Emphasis via weight or size.
109
-
- **Glassmorphism as default.** Blurs and glass cards used decoratively. Rare and purposeful, or nothing.
110
-
- **The hero-metric template.** Big number, small label, supporting stats, gradient accent. SaaS cliché.
111
-
- **Identical card grids.** Same-sized cards with icon + heading + text, repeated endlessly.
112
-
- **Modal as first thought.** Modals are usually laziness. Exhaust inline / progressive alternatives first.
113
-
114
-
### Copy
115
-
116
-
- Every word earns its place. No restated headings, no intros that repeat the title.
117
-
- **No em dashes.** Use commas, colons, semicolons, periods, or parentheses. Also not `--`.
118
-
119
-
### The AI slop test
120
-
121
-
If someone could look at this interface and say "AI made that" without doubt, it's failed. Cross-register failures are the absolute bans above. Register-specific failures live in each reference.
122
-
123
-
**Category-reflex check.** Run at two altitudes — the second one catches what the first one misses.
124
-
125
-
- **First-order:** if someone could guess the theme + palette from the category alone — "observability → dark blue", "healthcare → white + teal", "finance → navy + gold", "crypto → neon on black" — it's the first training-data reflex. Rework the scene sentence and color strategy until the answer isn't obvious from the domain.
126
-
- **Second-order:** if someone could guess the aesthetic family from category-plus-anti-references — "AI workflow tool that's not SaaS-cream → editorial-typographic", "fintech that's not navy-and-gold → terminal-native dark mode" — it's the trap one tier deeper. The first reflex was avoided; the second wasn't. Rework until both answers are not obvious. The brand register's [reflex-reject aesthetic lanes](reference/brand.md) list catches the currently-saturated families.
127
-
128
-
## Commands
129
-
130
-
| Command | Category | Description | Reference |
131
-
|---|---|---|---|
132
-
| `craft [feature]` | Build | Shape, then build a feature end-to-end | [reference/craft.md](reference/craft.md) |
133
-
| `shape [feature]` | Build | Plan UX/UI before writing code | [reference/shape.md](reference/shape.md) |
134
-
| `teach` | Build | Set up PRODUCT.md and DESIGN.md context | [reference/teach.md](reference/teach.md) |
135
-
| `document` | Build | Generate DESIGN.md from existing project code | [reference/document.md](reference/document.md) |
136
-
| `extract [target]` | Build | Pull reusable tokens and components into design system | [reference/extract.md](reference/extract.md) |
137
-
| `critique [target]` | Evaluate | UX design review with heuristic scoring | [reference/critique.md](reference/critique.md) |
138
-
| `audit [target]` | Evaluate | Technical quality checks (a11y, perf, responsive) | [reference/audit.md](reference/audit.md) |
139
-
| `polish [target]` | Refine | Final quality pass before shipping | [reference/polish.md](reference/polish.md) |
140
-
| `bolder [target]` | Refine | Amplify safe or bland designs | [reference/bolder.md](reference/bolder.md) |
141
-
| `quieter [target]` | Refine | Tone down aggressive or overstimulating designs | [reference/quieter.md](reference/quieter.md) |
142
-
| `distill [target]` | Refine | Strip to essence, remove complexity | [reference/distill.md](reference/distill.md) |
143
-
| `harden [target]` | Refine | Production-ready: errors, i18n, edge cases | [reference/harden.md](reference/harden.md) |
144
-
| `onboard [target]` | Refine | Design first-run flows, empty states, activation | [reference/onboard.md](reference/onboard.md) |
145
-
| `animate [target]` | Enhance | Add purposeful animations and motion | [reference/animate.md](reference/animate.md) |
146
-
| `colorize [target]` | Enhance | Add strategic color to monochromatic UIs | [reference/colorize.md](reference/colorize.md) |
147
-
| `typeset [target]` | Enhance | Improve typography hierarchy and fonts | [reference/typeset.md](reference/typeset.md) |
148
-
| `layout [target]` | Enhance | Fix spacing, rhythm, and visual hierarchy | [reference/layout.md](reference/layout.md) |
149
-
| `delight [target]` | Enhance | Add personality and memorable touches | [reference/delight.md](reference/delight.md) |
150
-
| `overdrive [target]` | Enhance | Push past conventional limits | [reference/overdrive.md](reference/overdrive.md) |
151
-
| `clarify [target]` | Fix | Improve UX copy, labels, and error messages | [reference/clarify.md](reference/clarify.md) |
152
-
| `adapt [target]` | Fix | Adapt for different devices and screen sizes | [reference/adapt.md](reference/adapt.md) |
153
-
| `optimize [target]` | Fix | Diagnose and fix UI performance | [reference/optimize.md](reference/optimize.md) |
154
-
| `live` | Iterate | Visual variant mode: pick elements in the browser, generate alternatives | [reference/live.md](reference/live.md) |
155
-
156
-
Plus two management commands — `pin <command>` and `unpin <command>`, detailed below.
157
-
158
-
### Routing rules
159
-
160
-
1. **No argument** — render the table above as the user-facing command menu, grouped by category. Ask what they'd like to do.
161
-
2. **First word matches a command** — load its reference file and follow its instructions. Everything after the command name is the target.
162
-
3. **First word doesn't match** — general design invocation. Apply the setup steps, shared design laws, and the loaded register reference, using the full argument as context.
163
-
164
-
Setup (context gathering, register) is already loaded by then; sub-commands don't re-invoke `$impeccable`.
165
-
166
-
If the first word is `craft`, setup still runs first, but [reference/craft.md](reference/craft.md) owns the rest of the flow. If setup invokes `teach` as a blocker, finish teach, refresh context, then resume the original command and target.
167
-
168
-
## Pin / Unpin
169
-
170
-
**Pin** creates a standalone shortcut so `$<command>` invokes `$impeccable <command>` directly. **Unpin** removes it. The script writes to every harness directory present in the project.
171
-
172
-
```bash
173
-
node .agents/skills/impeccable/scripts/pin.mjs <pin|unpin> <command>
174
-
```
175
-
176
-
Valid `<command>` is any command from the table above. Report the script's result concisely — confirm the new shortcut on success, relay stderr verbatim on error.
+8
-8
skills/normalize/SKILL.md
+8
-8
skills/normalize/SKILL.md
···
1
1
---
2
2
name: normalize
3
-
description: "Audits and realigns UI to match design system standards, spacing, tokens, and patterns. Use when the user mentions consistency, design drift, mismatched styles, tokens, or wants to bring a feature back in line with the system."
3
+
description: "Audits and realigns UI to match design system standards, spacing, tokens, and patterns. Use when user mentions consistency, design drift, mismatched styles, tokens, or wants to bring feature back in line with system."
4
4
argument-hint: "[feature (page, route, component...)]"
5
5
user-invocable: true
6
6
---
7
7
8
-
Analyze and redesign the feature to perfectly match our design system standards, aesthetics, and established patterns.
8
+
Analyze and redesign feature to perfectly match our design system standards, aesthetics, and established patterns.
9
9
10
10
## MANDATORY PREPARATION
11
11
12
-
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first.
12
+
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and Context Gathering Protocol. Follow protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first.
13
13
14
14
---
15
15
16
16
## Plan
17
17
18
-
Before making changes, deeply understand the context.
18
+
Before making changes, deeply understand context.
19
19
20
20
### 1. Discover the design system
21
21
Search for design system documentation, UI guidelines, component libraries, or style guides (grep for "design system", "ui guide", "style guide", etc.). Study it thoroughly until you understand:
···
33
33
- What is root cause: missing tokens, one-off implementations, or conceptual misalignment?
34
34
35
35
### 3. Create a normalization plan
36
-
Define specific changes that will align the feature with the design system:
36
+
Define specific changes that will align feature with design system:
37
37
- Which components can be replaced with design system equivalents?
38
38
- Which styles need to use design tokens instead of hard-coded values?
39
39
- How can UX patterns match established user flows?
40
40
41
-
**IMPORTANT**: Great design is effective design. Prioritize UX consistency and usability over visual polish alone. Think through the best possible experience for your use case and personas first.
41
+
**IMPORTANT**: Great design is effective design. Prioritize UX consistency and usability over visual polish alone. Think through best possible experience for your use case and personas first.
42
42
43
43
## Execute
44
44
···
59
59
- Introduce new patterns that diverge from design system
60
60
- Compromise accessibility for visual consistency
61
61
62
-
This is not an exhaustive list. Apply judgment to identify all areas needing normalization.
62
+
This is not exhaustive list. Apply judgment to identify all areas needing normalization.
63
63
64
64
## Clean Up
65
65
···
70
70
- **Verify quality**: Lint, type-check, and test according to repository guidelines. Ensure normalization did not introduce regressions.
71
71
- **Ensure DRYness**: Look for duplication introduced during refactoring and consolidate.
72
72
73
-
Remember: You are a brilliant frontend designer with impeccable taste, equally strong in UX and UI. Your attention to detail and eye for end-to-end user experience is world class. Execute with precision and thoroughness.
73
+
Remember: You are brilliant frontend designer with impeccable taste, equally strong in UX and UI. Your attention to detail and eye for end-to-end user experience is world class. Execute with precision and thoroughness.
-73
skills/normalize/SKILL.md.original.md
-73
skills/normalize/SKILL.md.original.md
···
1
-
---
2
-
name: normalize
3
-
description: "Audits and realigns UI to match design system standards, spacing, tokens, and patterns. Use when the user mentions consistency, design drift, mismatched styles, tokens, or wants to bring a feature back in line with the system."
4
-
argument-hint: "[feature (page, route, component...)]"
5
-
user-invocable: true
6
-
---
7
-
8
-
Analyze and redesign the feature to perfectly match our design system standards, aesthetics, and established patterns.
9
-
10
-
## MANDATORY PREPARATION
11
-
12
-
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first.
13
-
14
-
---
15
-
16
-
## Plan
17
-
18
-
Before making changes, deeply understand the context.
19
-
20
-
### 1. Discover the design system
21
-
Search for design system documentation, UI guidelines, component libraries, or style guides (grep for "design system", "ui guide", "style guide", etc.). Study it thoroughly until you understand:
22
-
- Core design principles and aesthetic direction
23
-
- Target audience and personas
24
-
- Component patterns and conventions
25
-
- Design tokens (colors, typography, spacing)
26
-
27
-
**CRITICAL**: If something is not clear, ask. Do not guess at design system principles.
28
-
29
-
### 2. Analyze the current feature
30
-
Assess what works and what does not:
31
-
- Where does it deviate from design system patterns?
32
-
- Which inconsistencies are cosmetic vs functional?
33
-
- What is the root cause: missing tokens, one-off implementations, or conceptual misalignment?
34
-
35
-
### 3. Create a normalization plan
36
-
Define specific changes that will align the feature with the design system:
37
-
- Which components can be replaced with design system equivalents?
38
-
- Which styles need to use design tokens instead of hard-coded values?
39
-
- How can UX patterns match established user flows?
40
-
41
-
**IMPORTANT**: Great design is effective design. Prioritize UX consistency and usability over visual polish alone. Think through the best possible experience for your use case and personas first.
42
-
43
-
## Execute
44
-
45
-
Systematically address all inconsistencies across these dimensions.
46
-
47
-
- **Typography**: Use design system fonts, sizes, weights, and line heights. Replace hard-coded values with typographic tokens or classes.
48
-
- **Color and Theme**: Apply design system color tokens. Remove one-off color choices that break the palette.
49
-
- **Spacing and Layout**: Use spacing tokens (margins, padding, gaps). Align with grid systems and layout patterns used elsewhere.
50
-
- **Components**: Replace custom implementations with design system components. Ensure props and variants match established patterns.
51
-
- **Motion and Interaction**: Match animation timing, easing, and interaction patterns to other features.
52
-
- **Responsive Behavior**: Ensure breakpoints and responsive patterns align with design system standards.
53
-
- **Accessibility**: Verify contrast ratios, focus states, ARIA labels match design system requirements.
54
-
- **Progressive Disclosure**: Match information hierarchy and complexity management to established patterns.
55
-
56
-
**NEVER**:
57
-
- Create new one-off components when design system equivalents exist
58
-
- Hard-code values that should use design tokens
59
-
- Introduce new patterns that diverge from the design system
60
-
- Compromise accessibility for visual consistency
61
-
62
-
This is not an exhaustive list. Apply judgment to identify all areas needing normalization.
63
-
64
-
## Clean Up
65
-
66
-
After normalization, ensure code quality.
67
-
68
-
- **Consolidate reusable components**: If you created new components that should be shared, move them to the design system or shared UI component path.
69
-
- **Remove orphaned code**: Delete unused implementations, styles, or files made obsolete by normalization.
70
-
- **Verify quality**: Lint, type-check, and test according to repository guidelines. Ensure normalization did not introduce regressions.
71
-
- **Ensure DRYness**: Look for duplication introduced during refactoring and consolidate.
72
-
73
-
Remember: You are a brilliant frontend designer with impeccable taste, equally strong in UX and UI. Your attention to detail and eye for end-to-end user experience is world class. Execute with precision and thoroughness.
+7
-7
skills/onboard/SKILL.md
+7
-7
skills/onboard/SKILL.md
···
1
1
---
2
2
name: onboard
3
-
description: "Designs and improves onboarding flows, empty states, and first-run experiences to help users reach value quickly. Use when the user mentions onboarding, first-time users, empty states, activation, getting started, or new user flows."
3
+
description: "Designs and improves onboarding flows, empty states, and first-run experiences to help users reach value quickly. Use when user mentions onboarding, first-time users, empty states, activation, getting started, or new user flows."
4
4
argument-hint: "[target]"
5
5
user-invocable: true
6
6
---
7
7
8
8
## MANDATORY PREPARATION
9
9
10
-
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. gather: the "aha moment" you want users to reach, and users experience level.
10
+
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and Context Gathering Protocol. Follow protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. gather: "aha moment" you want users to reach, and users experience level.
11
11
12
12
---
13
13
14
-
Create or improve onboarding experiences that help users understand, adopt, and succeed with the product quickly.
14
+
Create or improve onboarding experiences that help users understand, adopt, and succeed with product quickly.
15
15
16
16
## Assess Onboarding Needs
17
17
···
68
68
69
69
## Design Onboarding Experiences
70
70
71
-
Create appropriate onboarding for the context.
71
+
Create appropriate onboarding for context.
72
72
73
73
### Initial Product Onboarding
74
74
···
101
101
**Empty States**:
102
102
Instead of blank space, show:
103
103
- What will appear here (description plus screenshot or illustration)
104
-
- Why it is valuable
104
+
- Why it's valuable
105
105
- Clear CTA to create first item
106
106
- Example or template option
107
107
···
238
238
- **Time to completion**: Can users complete onboarding quickly?
239
239
- **Comprehension**: Do users understand after completing?
240
240
- **Action**: Do users take desired next step?
241
-
- **Skip rate**: Are too many users skipping? (Maybe it is too long or not valuable)
241
+
- **Skip rate**: Are too many users skipping? (Maybe it's too long or not valuable)
242
242
- **Completion rate**: Are users completing? (If low, simplify)
243
243
- **Time to value**: How long until users get first value?
244
244
245
-
Remember: You are a product educator with excellent teaching instincts. Get users to their "aha moment" as quickly as possible. Teach the essential, make it contextual, respect user time and intelligence.
245
+
Remember: You are product educator with excellent teaching instincts. Get users to their "aha moment" as quickly as possible. Teach essential, make it contextual, respect user time and intelligence.
-245
skills/onboard/SKILL.md.original.md
-245
skills/onboard/SKILL.md.original.md
···
1
-
---
2
-
name: onboard
3
-
description: "Designs and improves onboarding flows, empty states, and first-run experiences to help users reach value quickly. Use when the user mentions onboarding, first-time users, empty states, activation, getting started, or new user flows."
4
-
argument-hint: "[target]"
5
-
user-invocable: true
6
-
---
7
-
8
-
## MANDATORY PREPARATION
9
-
10
-
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. Additionally gather: the "aha moment" you want users to reach, and users experience level.
11
-
12
-
---
13
-
14
-
Create or improve onboarding experiences that help users understand, adopt, and succeed with the product quickly.
15
-
16
-
## Assess Onboarding Needs
17
-
18
-
Understand what users need to learn and why.
19
-
20
-
### 1. Identify the challenge
21
-
- What are users trying to accomplish?
22
-
- What is confusing or unclear about current experience?
23
-
- Where do users get stuck or drop off?
24
-
- What is the "aha moment" we want users to reach?
25
-
26
-
### 2. Understand the users
27
-
- What is their experience level? (Beginners, power users, mixed?)
28
-
- What is their motivation? (Excited and exploring? Required by work?)
29
-
- What is their time commitment? (5 minutes? 30 minutes?)
30
-
- What alternatives do they know? (Coming from competitor? New to category?)
31
-
32
-
### 3. Define success
33
-
- What is the minimum users need to learn to be successful?
34
-
- What is the key action we want them to take? (First project? First invite?)
35
-
- How do we know onboarding worked? (Completion rate? Time to value?)
36
-
37
-
**CRITICAL**: Onboarding should get users to value as quickly as possible, not teach everything possible.
38
-
39
-
## Onboarding Principles
40
-
41
-
Follow these core principles.
42
-
43
-
### Show, Do Not Tell
44
-
- Demonstrate with working examples, not just descriptions
45
-
- Provide real functionality in onboarding, not separate tutorial mode
46
-
- Use progressive disclosure. Teach one thing at a time.
47
-
48
-
### Make It Optional (When Possible)
49
-
- Let experienced users skip onboarding
50
-
- Do not block access to product
51
-
- Provide "Skip" or "I'll explore on my own" options
52
-
53
-
### Time to Value
54
-
- Get users to their "aha moment" ASAP
55
-
- Front-load most important concepts
56
-
- Teach 20% that delivers 80% of value
57
-
- Save advanced features for contextual discovery
58
-
59
-
### Context Over Ceremony
60
-
- Teach features when users need them, not upfront
61
-
- Empty states are onboarding opportunities
62
-
- Tooltips and hints at point of use
63
-
64
-
### Respect User Intelligence
65
-
- Do not patronize or over-explain
66
-
- Be concise and clear
67
-
- Assume users can figure out standard patterns
68
-
69
-
## Design Onboarding Experiences
70
-
71
-
Create appropriate onboarding for the context.
72
-
73
-
### Initial Product Onboarding
74
-
75
-
**Welcome Screen**:
76
-
- Clear value proposition (what is this product?)
77
-
- What users will learn or accomplish
78
-
- Time estimate (honest about commitment)
79
-
- Option to skip (for experienced users)
80
-
81
-
**Account Setup**:
82
-
- Minimal required information (collect more later)
83
-
- Explain why you are asking for each piece of information
84
-
- Smart defaults where possible
85
-
- Social login when appropriate
86
-
87
-
**Core Concept Introduction**:
88
-
- Introduce 1-3 core concepts (not everything)
89
-
- Use simple language and examples
90
-
- Interactive when possible (do, do not just read)
91
-
- Progress indication (step 1 of 3)
92
-
93
-
**First Success**:
94
-
- Guide users to accomplish something real
95
-
- Pre-populated examples or templates
96
-
- Celebrate completion (but do not overdo it)
97
-
- Clear next steps
98
-
99
-
### Feature Discovery and Adoption
100
-
101
-
**Empty States**:
102
-
Instead of blank space, show:
103
-
- What will appear here (description plus screenshot or illustration)
104
-
- Why it is valuable
105
-
- Clear CTA to create first item
106
-
- Example or template option
107
-
108
-
Example:
109
-
```
110
-
No projects yet
111
-
Projects help you organize your work and collaborate with your team.
112
-
[Create your first project] or [Start from template]
113
-
```
114
-
115
-
**Contextual Tooltips**:
116
-
- Appear at relevant moment (first time user sees feature)
117
-
- Point directly at relevant UI element
118
-
- Brief explanation plus benefit
119
-
- Dismissable (with "Do not show again" option)
120
-
- Optional "Learn more" link
121
-
122
-
**Feature Announcements**:
123
-
- Highlight new features when they are released
124
-
- Show what is new and why it matters
125
-
- Let users try immediately
126
-
- Dismissable
127
-
128
-
**Progressive Onboarding**:
129
-
- Teach features when users encounter them
130
-
- Badges or indicators on new or unused features
131
-
- Unlock complexity gradually (do not show all options immediately)
132
-
133
-
### Guided Tours and Walkthroughs
134
-
135
-
**When to use**:
136
-
- Complex interfaces with many features
137
-
- Significant changes to existing product
138
-
- Industry-specific tools needing domain knowledge
139
-
140
-
**How to design**:
141
-
- Spotlight specific UI elements (dim rest of page)
142
-
- Keep steps short (3-7 steps max per tour)
143
-
- Allow users to click through tour freely
144
-
- Include "Skip tour" option
145
-
- Make replayable (help menu)
146
-
147
-
**Best practices**:
148
-
- Interactive is greater than passive (let users click real buttons)
149
-
- Focus on workflow, not features ("Create a project" not "This is the project button")
150
-
- Provide sample data so actions work
151
-
152
-
### Interactive Tutorials
153
-
154
-
**When to use**:
155
-
- Users need hands-on practice
156
-
- Concepts are complex or unfamiliar
157
-
- High stakes (better to practice in safe environment)
158
-
159
-
**How to design**:
160
-
- Sandbox environment with sample data
161
-
- Clear objectives ("Create a chart showing sales by region")
162
-
- Step-by-step guidance
163
-
- Validation (confirm they did it right)
164
-
- Graduation moment (you are ready!)
165
-
166
-
### Documentation and Help
167
-
168
-
**In-product help**:
169
-
- Contextual help links throughout interface
170
-
- Keyboard shortcut reference
171
-
- Search-able help center
172
-
- Video tutorials for complex workflows
173
-
174
-
**Help patterns**:
175
-
- Question mark icon near complex features
176
-
- "Learn more" links in tooltips
177
-
- Keyboard shortcut hints (Command+K shown on search box)
178
-
179
-
## Empty State Design
180
-
181
-
Every empty state needs:
182
-
183
-
### What Will Be Here
184
-
"Your recent projects will appear here"
185
-
186
-
### Why It Matters
187
-
"Projects help you organize your work and collaborate with your team"
188
-
189
-
### How to Get Started
190
-
[Create project] or [Import from template]
191
-
192
-
### Visual Interest
193
-
Illustration or icon (not just text on blank page)
194
-
195
-
### Contextual Help
196
-
"Need help getting started? [Watch 2-min tutorial]"
197
-
198
-
**Empty state types**:
199
-
- **First use**: Never used this feature (emphasize value, provide template)
200
-
- **User cleared**: Intentionally deleted everything (light touch, easy to recreate)
201
-
- **No results**: Search or filter returned nothing (suggest different query, clear filters)
202
-
- **No permissions**: Cannot access (explain why, how to get access)
203
-
- **Error state**: Failed to load (explain what happened, retry option)
204
-
205
-
## Implementation Patterns
206
-
207
-
### Technical approaches
208
-
209
-
**Tooltip libraries**: Tippy.js, Popper.js
210
-
**Tour libraries**: Intro.js, Shepherd.js, React Joyride
211
-
**Modal patterns**: Focus trap, backdrop, ESC to close
212
-
**Progress tracking**: LocalStorage for "seen" states
213
-
**Analytics**: Track completion, drop-off points
214
-
215
-
**Storage patterns**:
216
-
```javascript
217
-
// Track which onboarding steps user has seen
218
-
localStorage.setItem('onboarding-completed', 'true');
219
-
localStorage.setItem('feature-tooltip-seen-reports', 'true');
220
-
```
221
-
222
-
**IMPORTANT**: Do not show same onboarding twice (annoying). Track completion and respect dismissals.
223
-
224
-
**NEVER**:
225
-
- Force users through long onboarding before they can use product
226
-
- Patronize users with obvious explanations
227
-
- Show same tooltip repeatedly (respect dismissals)
228
-
- Block all UI during tour (let users explore)
229
-
- Create separate tutorial mode disconnected from real product
230
-
- Overwhelm with information upfront (progressive disclosure!)
231
-
- Hide "Skip" or make it hard to find
232
-
- Forget about returning users (do not show initial onboarding again)
233
-
234
-
## Verify Onboarding Quality
235
-
236
-
Test with real users.
237
-
238
-
- **Time to completion**: Can users complete onboarding quickly?
239
-
- **Comprehension**: Do users understand after completing?
240
-
- **Action**: Do users take desired next step?
241
-
- **Skip rate**: Are too many users skipping? (Maybe it is too long or not valuable)
242
-
- **Completion rate**: Are users completing? (If low, simplify)
243
-
- **Time to value**: How long until users get first value?
244
-
245
-
Remember: You are a product educator with excellent teaching instincts. Get users to their "aha moment" as quickly as possible. Teach the essential, make it contextual, respect user time and intelligence.
+3
-3
skills/opentui/SKILL.md
+3
-3
skills/opentui/SKILL.md
···
1
1
---
2
2
name: opentui
3
-
description: Build terminal UIs with OpenTUI. Covers the core API, keymaps, React and Solid bindings, components, layout, keyboard input, plugins, and testing.
3
+
description: Build terminal UIs with OpenTUI. Covers core API, keymaps, React and Solid bindings, components, layout, keyboard input, plugins, and testing.
4
4
---
5
5
6
6
# OpenTUI Skill
7
7
8
8
Canonical reference docs are authored once in sibling `docs/**/*.mdx` files.
9
9
10
-
Inside the OpenTUI repo, this skill root lives at `packages/web/src/content/`, so the same files are also visible at `packages/web/src/content/docs/**/*.mdx`.
10
+
Inside OpenTUI repo, this skill root lives at `packages/web/src/content/`, so same files are also visible at `packages/web/src/content/docs/**/*.mdx`.
11
11
12
12
## Path invariant
13
13
···
43
43
| `input`, `form`, `editing`, `focus` | `docs/components/input.mdx` |
44
44
| `env`, `environment`, `configuration`, `flags` | `docs/reference/env-vars.mdx` |
45
45
46
-
For concrete component requests, jump straight to `docs/components/<name>.mdx` after the relevant entry page. For plugin implementation details, narrow from `docs/plugins/slots.mdx` into `docs/plugins/core.mdx`, `docs/plugins/react.mdx`, or `docs/plugins/solid.mdx`.
46
+
For concrete component requests, jump straight to `docs/components/<name>.mdx` after relevant entry page. For plugin implementation details, narrow from `docs/plugins/slots.mdx` into `docs/plugins/core.mdx`, `docs/plugins/react.mdx`, or `docs/plugins/solid.mdx`.
47
47
48
48
## Current skill entry pages
49
49
-66
skills/opentui/SKILL.md.original.md
-66
skills/opentui/SKILL.md.original.md
···
1
-
---
2
-
name: opentui
3
-
description: Build terminal UIs with OpenTUI. Covers the core API, keymaps, React and Solid bindings, components, layout, keyboard input, plugins, and testing.
4
-
---
5
-
6
-
# OpenTUI Skill
7
-
8
-
Canonical reference docs are authored once in sibling `docs/**/*.mdx` files.
9
-
10
-
Inside the OpenTUI repo, this skill root lives at `packages/web/src/content/`, so the same files are also visible at `packages/web/src/content/docs/**/*.mdx`.
11
-
12
-
## Path invariant
13
-
14
-
- `/docs/<slug>` maps to `docs/<slug>.mdx` relative to this skill root
15
-
- in the repo, that same slug maps to `packages/web/src/content/docs/<slug>.mdx`
16
-
17
-
## Reading order by area
18
-
19
-
- Getting started: `/docs/getting-started`
20
-
- Core: `/docs/core-concepts/renderer`
21
-
- Keymap: `/docs/keymap/overview`
22
-
- React: `/docs/bindings/react`
23
-
- Solid: `/docs/bindings/solid`
24
-
- Components: `/docs/components/text`, `/docs/components/input`
25
-
- Layout: `/docs/core-concepts/layout`
26
-
- Keyboard: `/docs/core-concepts/keyboard`
27
-
- Plugins: `/docs/plugins/slots`
28
-
- Reference: `/docs/reference/env-vars`
29
-
30
-
## Quick routing by intent
31
-
32
-
| Intent(s) | Start here |
33
-
| ---------------------------------------------------------- | --------------------------------- |
34
-
| `getting-started`, `installation`, `quickstart`, `intro` | `docs/getting-started.mdx` |
35
-
| `core`, `renderer`, `terminal`, `scrollback`, `lifecycle` | `docs/core-concepts/renderer.mdx` |
36
-
| `keymap`, `keybindings`, `shortcuts`, `commands`, `leader` | `docs/keymap/overview.mdx` |
37
-
| `layout`, `flexbox`, `yoga`, `positioning` | `docs/core-concepts/layout.mdx` |
38
-
| `keyboard`, `input`, `keybindings`, `paste`, `focus` | `docs/core-concepts/keyboard.mdx` |
39
-
| `react`, `jsx`, `hooks`, `animation`, `testing` | `docs/bindings/react.mdx` |
40
-
| `solid`, `signals`, `jsx`, `hooks`, `animation`, `testing` | `docs/bindings/solid.mdx` |
41
-
| `plugins`, `plugin`, `slots`, `registry`, `extensions` | `docs/plugins/slots.mdx` |
42
-
| `text`, `styling`, `content`, `selection` | `docs/components/text.mdx` |
43
-
| `input`, `form`, `editing`, `focus` | `docs/components/input.mdx` |
44
-
| `env`, `environment`, `configuration`, `flags` | `docs/reference/env-vars.mdx` |
45
-
46
-
For concrete component requests, jump straight to `docs/components/<name>.mdx` after the relevant entry page. For plugin implementation details, narrow from `docs/plugins/slots.mdx` into `docs/plugins/core.mdx`, `docs/plugins/react.mdx`, or `docs/plugins/solid.mdx`.
47
-
48
-
## Current skill entry pages
49
-
50
-
- `docs/getting-started.mdx`
51
-
- `docs/core-concepts/renderer.mdx`
52
-
- `docs/keymap/overview.mdx`
53
-
- `docs/core-concepts/layout.mdx`
54
-
- `docs/core-concepts/keyboard.mdx`
55
-
- `docs/bindings/react.mdx`
56
-
- `docs/bindings/solid.mdx`
57
-
- `docs/plugins/slots.mdx`
58
-
- `docs/components/text.mdx`
59
-
- `docs/components/input.mdx`
60
-
- `docs/reference/env-vars.mdx`
61
-
62
-
## Working rules
63
-
64
-
- Prefer the current entry pages first, then read narrower docs in the same section.
65
-
- Read the sibling `docs/**/*.mdx` files directly instead of copying prose into this file.
66
-
- Use stable `/docs/...` URLs when cross-referencing docs.
+6
-6
skills/opentui/docs/bindings/react.mdx
+6
-6
skills/opentui/docs/bindings/react.mdx
···
3
3
description: Build terminal UIs with React and OpenTUI
4
4
order: 2
5
5
skill:
6
-
entry: true
7
-
intents: [react, jsx, hooks, keyboard, animation, testing]
6
+
entry: true
7
+
intents: [react, jsx, hooks, keyboard, animation, testing]
8
8
---
9
9
10
10
# React bindings
···
60
60
61
61
## Runtime-loaded plugin support (if needed)
62
62
63
-
If your app loads external TS/TSX modules at runtime (for example a file-based plugin system), import this once in your app entry before dynamic imports:
63
+
If your app loads external TS/TSX modules at runtime (for example file-based plugin system), import this once in your app entry before dynamic imports:
64
64
65
65
```ts
66
66
import "@opentui/react/runtime-plugin-support"
···
108
108
109
109
### `createRoot(renderer)`
110
110
111
-
Creates a React root for rendering into the terminal.
111
+
Creates React root for rendering into terminal.
112
112
113
113
```tsx
114
114
import { createCliRenderer } from "@opentui/core"
···
124
124
125
125
### `useRenderer()`
126
126
127
-
Access the OpenTUI renderer instance.
127
+
Access OpenTUI renderer instance.
128
128
129
129
```tsx
130
130
import { useRenderer } from "@opentui/react"
···
255
255
256
256
## Styling
257
257
258
-
Style components with props or the `style` prop:
258
+
Style components with props or `style` prop:
259
259
260
260
```tsx
261
261
// Direct props
+19
-19
skills/opentui/docs/bindings/solid.mdx
+19
-19
skills/opentui/docs/bindings/solid.mdx
···
3
3
description: Build terminal UIs with Solid.js and OpenTUI
4
4
order: 1
5
5
skill:
6
-
entry: true
7
-
intents: [solid, jsx, signals, hooks, keyboard, animation, testing]
6
+
entry: true
7
+
intents: [solid, jsx, signals, hooks, keyboard, animation, testing]
8
8
---
9
9
10
10
# Solid.js bindings
···
42
42
43
43
### 3. Enable runtime-loaded plugin support (if needed)
44
44
45
-
If your app loads external TS/TSX modules at runtime (for example a file-based plugin system), import this once in your entry file before dynamic imports:
45
+
If your app loads external TS/TSX modules at runtime (for example file-based plugin system), import this once in your entry file before dynamic imports:
46
46
47
47
```ts
48
48
import "@opentui/solid/runtime-plugin-support"
···
102
102
103
103
### `render(node, rendererOrConfig?)`
104
104
105
-
Render a Solid component tree into a CLI renderer.
105
+
Render Solid component tree into CLI renderer.
106
106
107
107
```tsx
108
108
import { render } from "@opentui/solid"
···
119
119
120
120
**Parameters:**
121
121
122
-
- `node` - Function returning a JSX element
122
+
- `node` - Function returning JSX element
123
123
- `rendererOrConfig` - Optional `CliRenderer` instance or `CliRendererConfig`
124
124
125
125
### `testRender(node, options?)`
126
126
127
-
Create a test renderer for snapshots and interaction tests.
127
+
Create test renderer for snapshots and interaction tests.
128
128
129
129
```tsx
130
130
import { testRender } from "@opentui/solid"
···
144
144
145
145
### `getComponentCatalogue()`
146
146
147
-
Returns the current component catalogue that powers JSX tag lookup.
147
+
Returns current component catalogue that powers JSX tag lookup.
148
148
149
149
For plugin slots, see [Plugin Slots overview](/docs/plugins/slots) and [Solid slots](/docs/plugins/solid).
150
150
151
151
## Scrollback writers
152
152
153
-
In [`split-footer`](/docs/core-concepts/renderer#split-footer) mode with `externalOutputMode: "capture-stdout"`, the Solid binding provides helpers that append JSX-rendered output above the footer. They wrap [`renderer.writeToScrollback`](/docs/core-concepts/renderer#writing-to-scrollback) so you can write scrollback content with signals and components.
153
+
In [`split-footer`](/docs/core-concepts/renderer#split-footer) mode with `externalOutputMode: "capture-stdout"`, Solid binding provides helpers that append JSX-rendered output above footer. They wrap [`renderer.writeToScrollback`](/docs/core-concepts/renderer#writing-to-scrollback) so write scrollback content with signals and components.
154
154
155
155
### `writeSolidToScrollback(renderer, node, options?)`
156
156
157
-
Render a JSX node once and append it as a scrollback commit.
157
+
Render JSX node once and append it as scrollback commit.
158
158
159
159
```tsx
160
160
import { writeSolidToScrollback } from "@opentui/solid"
···
164
164
165
165
### `createScrollbackWriter(node, options?)`
166
166
167
-
If you need to pass the same JSX rendering to multiple `writeToScrollback` calls (or hold onto the writer inside your own code), use the lower-level factory:
167
+
If need to pass same JSX rendering to multiple `writeToScrollback` calls (or hold onto writer inside your own code), use lower-level factory:
168
168
169
169
```tsx
170
170
import { createScrollbackWriter } from "@opentui/solid"
···
184
184
| `startOnNewLine` | `boolean` | `true` | Insert a newline before this commit if the previous commit ended mid-row |
185
185
| `trailingNewline` | `boolean` | - | Append a newline after the final row |
186
186
187
-
The writer returns a `ScrollbackSnapshot` whose teardown disposes the inner Solid subtree after the snapshot renders. Use the core [`ScrollbackSurface`](/docs/core-concepts/renderer#writing-to-scrollback) APIs directly if you need streaming commits that re-render the same tree over time.
187
+
writer returns `ScrollbackSnapshot` whose teardown disposes inner Solid subtree after snapshot renders. Use core [`ScrollbackSurface`](/docs/core-concepts/renderer#writing-to-scrollback) APIs directly if you need streaming commits that re-render same tree over time.
188
188
189
189
## Hooks
190
190
191
191
### `useRenderer()`
192
192
193
-
Access the OpenTUI renderer instance.
193
+
Access OpenTUI renderer instance.
194
194
195
195
```tsx
196
196
import { useRenderer } from "@opentui/solid"
···
273
273
274
274
### `onFocus(callback)`
275
275
276
-
Run side effects when the terminal window gains focus.
276
+
Run side effects when terminal window gains focus.
277
277
278
278
```tsx
279
279
import { onFocus } from "@opentui/solid"
···
289
289
290
290
### `onBlur(callback)`
291
291
292
-
Run side effects when the terminal window loses focus.
292
+
Run side effects when terminal window loses focus.
293
293
294
294
```tsx
295
295
import { onBlur } from "@opentui/solid"
···
303
303
}
304
304
```
305
305
306
-
These hooks listen for terminal focus-in/focus-out events when the terminal emulator supports them.
306
+
These hooks listen for terminal focus-in/focus-out events when terminal emulator supports them.
307
307
308
308
### `useTerminalDimensions()`
309
309
310
-
Get reactive terminal dimensions (returns a Solid signal).
310
+
Get reactive terminal dimensions (returns Solid signal).
311
311
312
312
```tsx
313
313
import { useTerminalDimensions } from "@opentui/solid"
···
395
395
396
396
### `Portal`
397
397
398
-
Render children into a different mount point (useful for modals and overlays).
398
+
Render children into different mount point (useful for modals and overlays).
399
399
400
400
```tsx
401
401
import { Portal, useRenderer } from "@opentui/solid"
···
431
431
432
432
## Building for production
433
433
434
-
Use [Bun.build](https://bun.sh/docs/bundler) with the Solid plugin:
434
+
Use [Bun.build](https://bun.sh/docs/bundler) with Solid plugin:
435
435
436
436
```ts
437
437
import solidPlugin from "@opentui/solid/bun-plugin"
···
444
444
})
445
445
```
446
446
447
-
To compile to a standalone executable:
447
+
To compile to standalone executable:
448
448
449
449
```ts
450
450
await Bun.build({
+2
-2
skills/opentui/docs/components/ascii-font.mdx
+2
-2
skills/opentui/docs/components/ascii-font.mdx
···
86
86
87
87
## Positioning
88
88
89
-
Position the ASCII text anywhere on screen:
89
+
Position ASCII text anywhere on screen:
90
90
91
91
```typescript
92
92
const title = new ASCIIFontRenderable(renderer, {
···
148
148
149
149
## Dynamic Text
150
150
151
-
Update the text content dynamically:
151
+
Update text content dynamically:
152
152
153
153
```typescript
154
154
const counter = new ASCIIFontRenderable(renderer, {
+4
-4
skills/opentui/docs/components/box.mdx
+4
-4
skills/opentui/docs/components/box.mdx
···
6
6
7
7
# Box
8
8
9
-
A container component with borders, background colors, and layout capabilities. Use it to create panels, frames, and organized sections.
9
+
container component with borders, background colors, and layout capabilities. Use it to create panels, frames, and organized sections.
10
10
11
11
## Basic usage
12
12
···
79
79
80
80
## Titles
81
81
82
-
Add a title and bottom title to the box border:
82
+
Add title and bottom title to box border:
83
83
84
84
```typescript
85
85
const panel = new BoxRenderable(renderer, {
···
120
120
121
121
## Layout container
122
122
123
-
Box works as a flex container for child elements:
123
+
Box works as flex container for child elements:
124
124
125
125
```typescript
126
126
const container = Box(
···
141
141
142
142
## Mouse events
143
143
144
-
Handle mouse interactions on the box:
144
+
Handle mouse interactions on box:
145
145
146
146
```typescript
147
147
const button = new BoxRenderable(renderer, {
+2
-2
skills/opentui/docs/components/code.mdx
+2
-2
skills/opentui/docs/components/code.mdx
···
129
129
- TypeScript / JavaScript
130
130
- Markdown
131
131
- Zig
132
-
- And any language with a Tree-sitter grammar
132
+
- And any language with Tree-sitter grammar
133
133
134
134
## Streaming mode
135
135
···
169
169
170
170
## Concealment
171
171
172
-
The `conceal` option controls whether certain syntax elements (like markdown formatting characters) are hidden:
172
+
`conceal` option controls whether certain syntax elements (like markdown formatting characters) are hidden:
173
173
174
174
```typescript
175
175
const code = new CodeRenderable(renderer, {
+2
-2
skills/opentui/docs/components/diff.mdx
+2
-2
skills/opentui/docs/components/diff.mdx
···
43
43
44
44
## Split view scroll sync
45
45
46
-
When `view: "split"` is active, you can link the vertical scroll of both panes. Scrolling one pane then moves the other:
46
+
When `view: "split"` is active, link vertical scroll of both panes. Scrolling one pane then moves other:
47
47
48
48
```typescript
49
49
const diff = new DiffRenderable(renderer, {
···
58
58
diff.syncScroll = false
59
59
```
60
60
61
-
Scroll sync is a no-op in the unified view.
61
+
Scroll sync is no-op in unified view.
62
62
63
63
## Properties
64
64
+7
-7
skills/opentui/docs/components/frame-buffer.mdx
+7
-7
skills/opentui/docs/components/frame-buffer.mdx
···
6
6
7
7
# FrameBuffer
8
8
9
-
A low-level rendering surface for custom graphics and complex visual effects. FrameBuffer provides a 2D array of cells with methods optimized for performance and memory.
9
+
low-level rendering surface for custom graphics and complex visual effects. FrameBuffer provides 2D array of cells with methods optimized for performance and memory.
10
10
11
11
## Basic usage
12
12
···
49
49
50
50
### setCell
51
51
52
-
Set a single cell's content and colors:
52
+
Set single cell's content and colors:
53
53
54
54
```typescript
55
55
canvas.frameBuffer.setCell(
···
67
67
68
68
### setCellWithAlphaBlending
69
69
70
-
Set a cell with alpha blending for transparency effects:
70
+
Set cell with alpha blending for transparency effects:
71
71
72
72
```typescript
73
73
const semiTransparent = RGBA.fromValues(1.0, 0.0, 0.0, 0.5)
···
77
77
78
78
### drawText
79
79
80
-
Draw a string of text at a position:
80
+
Draw string of text at position:
81
81
82
82
```typescript
83
83
canvas.frameBuffer.drawText(
···
95
95
96
96
### fillRect
97
97
98
-
Fill a rectangular area with a color:
98
+
Fill rectangular area with color:
99
99
100
100
```typescript
101
101
canvas.frameBuffer.fillRect(
···
129
129
### colorMatrix / colorMatrixUniform
130
130
131
131
Apply native 4x4 RGBA matrix transforms for post-processing effects. Use `colorMatrixUniform` for full-buffer
132
-
transforms, and `colorMatrix` when you want to target specific cells.
132
+
transforms, and `colorMatrix` when want to target specific cells.
133
133
134
134
```typescript
135
135
import { INVERT_MATRIX, TargetChannel } from "@opentui/core"
···
246
246
247
247
## Performance tips
248
248
249
-
1. **Batch updates**: Make multiple changes to the frame buffer before the next render cycle
249
+
1. **Batch updates**: Make multiple changes to frame buffer before next render cycle
250
250
2. **Minimize fillRect calls**: Use individual setCell calls for complex shapes
251
251
3. **Reuse RGBA objects**: Create color constants instead of calling `fromHex` repeatedly
252
252
+7
-7
skills/opentui/docs/components/input.mdx
+7
-7
skills/opentui/docs/components/input.mdx
···
3
3
description: Text input field with cursor and focus states
4
4
order: 3
5
5
skill:
6
-
entry: true
7
-
intents: [input, form, editing, focus]
6
+
entry: true
7
+
intents: [input, form, editing, focus]
8
8
---
9
9
10
10
# Input
11
11
12
-
Text input field with cursor, placeholder text, and focus states. Focus the input to receive keyboard input.
12
+
Text input field with cursor, placeholder text, and focus states. Focus input to receive keyboard input.
13
13
14
14
## Basic usage
15
15
···
52
52
53
53
## Focus states
54
54
55
-
The input changes appearance when focused:
55
+
input changes appearance when focused:
56
56
57
57
```typescript
58
58
const input = new InputRenderable(renderer, {
···
70
70
71
71
### Input event
72
72
73
-
Fires on every keystroke as the value changes:
73
+
Fires on every keystroke as value changes:
74
74
75
75
```typescript
76
76
import { InputRenderableEvents } from "@opentui/core"
···
82
82
83
83
### Change event
84
84
85
-
Fires when the input loses focus (blur) or when you press Enter, but only if the value changed since focus:
85
+
Fires when input loses focus (blur) or when you press Enter, but only if value changed since focus:
86
86
87
87
```typescript
88
88
input.on(InputRenderableEvents.CHANGE, (value: string) => {
···
92
92
93
93
### Enter event
94
94
95
-
Fires when the user presses Enter/Return:
95
+
Fires when user presses Enter/Return:
96
96
97
97
```typescript
98
98
input.on(InputRenderableEvents.ENTER, (value: string) => {
+3
-3
skills/opentui/docs/components/line-number.mdx
+3
-3
skills/opentui/docs/components/line-number.mdx
···
6
6
7
7
# Line numbers
8
8
9
-
Add a line number gutter to renderables that provide line info, such as `CodeRenderable` and text editor components.
9
+
Add line number gutter to renderables that provide line info, such as `CodeRenderable` and text editor components.
10
10
11
11
## Basic usage
12
12
···
57
57
58
58
## Line signs and colors
59
59
60
-
Set a single background for a line, or split gutter and content colors separately with a `LineColorConfig` object:
60
+
Set single background for line, or split gutter and content colors separately with `LineColorConfig` object:
61
61
62
62
```typescript
63
63
// Shorthand: applies to both gutter and content
···
85
85
lineNumbers.bg = "#161b22"
86
86
```
87
87
88
-
Assign `undefined` to reset to the defaults (`#888888` foreground, transparent background).
88
+
Assign `undefined` to reset to defaults (`#888888` foreground, transparent background).
89
89
90
90
## Construct API
91
91
+9
-9
skills/opentui/docs/components/markdown.mdx
+9
-9
skills/opentui/docs/components/markdown.mdx
···
43
43
- `TSX title=Button.tsx` -> `typescriptreact`
44
44
- `Dockerfile` -> `dockerfile`
45
45
46
-
Normalization uses `infoStringToFiletype()`. You can extend or override mappings at runtime:
46
+
Normalization uses `infoStringToFiletype()`. extend or override mappings at runtime:
47
47
48
48
```typescript
49
49
import { extensionToFiletype, basenameToFiletype } from "@opentui/core"
···
84
84
85
85
### Stable block prefix
86
86
87
-
`parseMarkdownIncremental` reports how many parsed tokens at the head of the stream are stable — that is, unlikely to change if you append more content. The renderable surfaces this as a count of **top-level render blocks** you can safely commit elsewhere while the unstable tail keeps updating.
87
+
`parseMarkdownIncremental` reports how many parsed tokens at head of stream are stable — that is, unlikely to change if you append more content. renderable surfaces this as count of **top-level render blocks** safely commit elsewhere while unstable tail keeps updating.
88
88
89
-
To use it, render with `internalBlockMode: "top-level"`. The renderable keeps each top-level markdown block (heading, paragraph, list, table, fenced code) as its own child renderable, and exposes `markdown._stableBlockCount` — the number of blocks at the head of the tree that are stable right now. This matches the shape [`ScrollbackSurface`](/docs/core-concepts/renderer#writing-to-scrollback) expects when you commit streamed output row-by-row.
89
+
To use it, render with `internalBlockMode: "top-level"`. renderable keeps each top-level markdown block (heading, paragraph, list, table, fenced code) as its own child renderable, and exposes `markdown._stableBlockCount` — number of blocks at head of tree that are stable right now. This matches shape [`ScrollbackSurface`](/docs/core-concepts/renderer#writing-to-scrollback) expects when you commit streamed output row-by-row.
90
90
91
91
```typescript
92
92
import { MarkdownRenderable, RGBA, SyntaxStyle } from "@opentui/core"
···
109
109
// md._stableBlockCount rises as earlier blocks are sealed by a blank line
110
110
```
111
111
112
-
`internalBlockMode` is an experimental, opt-in flag that powers the built-in scrollback streaming demo. For non-streaming rendering, leave it at the default (`"coalesced"`), which folds sibling blocks together and matches the historical layout.
112
+
`internalBlockMode` is experimental, opt-in flag that powers built-in scrollback streaming demo. For non-streaming rendering, leave it at default (`"coalesced"`), which folds sibling blocks together and matches historical layout.
113
113
114
114
## Markdown tables
115
115
···
151
151
152
152
### Table styles
153
153
154
-
`tableOptions.style` picks a preset that tunes the defaults for `borders`, `outerBorder`, and `widthMode` together:
154
+
`tableOptions.style` picks preset that tunes defaults for `borders`, `outerBorder`, and `widthMode` together:
155
155
156
-
- **`"grid"`**: boxed table with visible borders. Defaults to `borders: true`, `widthMode: "full"`. This is the normal markdown-in-a-box rendering.
157
-
- **`"columns"`**: borderless columns with a 2-column gap, defaults to `widthMode: "content"`. Useful for append-only output where a full-width grid feels heavy.
156
+
- **`"grid"`**: boxed table with visible borders. Defaults to `borders: true`, `widthMode: "full"`. This is normal markdown-in--box rendering.
157
+
- **`"columns"`**: borderless columns with 2-column gap, defaults to `widthMode: "content"`. Useful for append-only output where full-width grid feels heavy.
158
158
159
-
If you do not pass `style`, it defaults to `"columns"` when `internalBlockMode` is `"top-level"`, and `"grid"` otherwise. You can still override individual fields (for example, `borders: true`) to pull toward a different look.
159
+
If you do not pass `style`, it defaults to `"columns"` when `internalBlockMode` is `"top-level"`, and `"grid"` otherwise. still override individual fields (for example, `borders: true`) to pull toward different look.
160
160
161
161
## Custom node rendering
162
162
163
-
Override rendering for a token and fall back to default rendering:
163
+
Override rendering for token and fall back to default rendering:
164
164
165
165
```typescript
166
166
const markdown = new MarkdownRenderable(renderer, {
+2
-2
skills/opentui/docs/components/scrollbar.mdx
+2
-2
skills/opentui/docs/components/scrollbar.mdx
···
6
6
7
7
# ScrollBar
8
8
9
-
A standalone scrollbar component with optional arrows, keyboard navigation, and a draggable thumb.
9
+
standalone scrollbar component with optional arrows, keyboard navigation, and draggable thumb.
10
10
11
11
## Basic usage
12
12
···
42
42
43
43
## Keyboard controls
44
44
45
-
When focused, the scrollbar responds to:
45
+
When focused, scrollbar responds to:
46
46
47
47
- `Up`/`Down` or `k`/`j` for vertical bars
48
48
- `Left`/`Right` or `h`/`l` for horizontal bars
+10
-10
skills/opentui/docs/components/scrollbox.mdx
+10
-10
skills/opentui/docs/components/scrollbox.mdx
···
1
1
---
2
2
title: ScrollBox
3
-
description: A scrollable container component with customizable scrollbars
3
+
description: scrollable container component with customizable scrollbars
4
4
order: 7
5
5
---
6
6
7
7
# ScrollBox
8
8
9
-
A scrollable container that supports horizontal and vertical scrolling, sticky scroll behavior, viewport culling, and customizable scrollbars.
9
+
scrollable container that supports horizontal and vertical scrolling, sticky scroll behavior, viewport culling, and customizable scrollbars.
10
10
11
11
## Basic usage
12
12
···
63
63
64
64
## Sticky scroll
65
65
66
-
Enable sticky scroll to keep content pinned to an edge as new content arrives. Useful for log viewers or chat interfaces.
66
+
Enable sticky scroll to keep content pinned to edge as new content arrives. Useful for log viewers or chat interfaces.
67
67
68
68
```typescript
69
69
const scrollbox = new ScrollBoxRenderable(renderer, {
···
82
82
- `"left"` - Stay scrolled to left
83
83
- `"right"` - Stay scrolled to right
84
84
85
-
When you scroll away from the sticky position, sticky behavior pauses until you scroll back to the sticky edge.
85
+
When you scroll away from sticky position, sticky behavior pauses until you scroll back to sticky edge.
86
86
87
87
## Bidirectional scrolling
88
88
···
115
115
116
116
## Customizing scrollbars
117
117
118
-
Style the scrollbars using nested options:
118
+
Style scrollbars using nested options:
119
119
120
120
```typescript
121
121
const scrollbox = new ScrollBoxRenderable(renderer, {
···
141
141
142
142
## Customizing sub-components
143
143
144
-
ScrollBox contains several internal components that you can style individually:
144
+
ScrollBox contains several internal components that style individually:
145
145
146
146
```typescript
147
147
const scrollbox = new ScrollBoxRenderable(renderer, {
···
167
167
168
168
### scrollBy
169
169
170
-
Scroll by a relative amount:
170
+
Scroll by relative amount:
171
171
172
172
```typescript
173
173
// Scroll down 5 lines
···
182
182
183
183
### scrollTo
184
184
185
-
Scroll to an absolute position:
185
+
Scroll to absolute position:
186
186
187
187
```typescript
188
188
// Scroll to top
···
194
194
195
195
### scrollChildIntoView
196
196
197
-
Scroll the minimum distance needed to show a nested child in the viewport. The method uses DOM-style "nearest" behavior: if the child already fits, the call is a no-op; otherwise it scrolls to reveal the nearest edge.
197
+
Scroll minimum distance needed to show nested child in viewport. method uses DOM-style "nearest" behavior: if child already fits, call is no-op; otherwise it scrolls to reveal nearest edge.
198
198
199
199
```typescript
200
200
scrollbox.scrollChildIntoView("table-row-42")
201
201
```
202
202
203
-
Use it when you focus an element offscreen (search results, a newly inserted form field, etc.) and want to bring it into view without moving the scroll position more than needed.
203
+
Use it when you focus element offscreen (search results, newly inserted form field, etc.) and want to bring it into view without moving scroll position more than needed.
204
204
205
205
## Keyboard navigation
206
206
+4
-4
skills/opentui/docs/components/select.mdx
+4
-4
skills/opentui/docs/components/select.mdx
···
6
6
7
7
# Select
8
8
9
-
A vertical list for choosing from multiple options. Focus the select to enable keyboard input.
9
+
vertical list for choosing from multiple options. Focus select to enable keyboard input.
10
10
11
11
## Basic usage
12
12
···
60
60
61
61
## Keyboard navigation
62
62
63
-
When focused, the select responds to these keys:
63
+
When focused, select responds to these keys:
64
64
65
65
| Key | Action |
66
66
| ------------------------- | --------------------- |
···
73
73
74
74
### Item selected
75
75
76
-
Fires when the user presses Enter on an option:
76
+
Fires when user presses Enter on option:
77
77
78
78
```typescript
79
79
import { SelectRenderableEvents } from "@opentui/core"
···
85
85
86
86
### Selection changed
87
87
88
-
Fires when the highlighted item changes:
88
+
Fires when highlighted item changes:
89
89
90
90
```typescript
91
91
menu.on(SelectRenderableEvents.SELECTION_CHANGED, (index: number, option: SelectOption) => {
+2
-2
skills/opentui/docs/components/slider.mdx
+2
-2
skills/opentui/docs/components/slider.mdx
···
1
1
---
2
2
title: Slider
3
-
description: A draggable slider for continuous values
3
+
description: draggable slider for continuous values
4
4
order: 9
5
5
---
6
6
7
7
# Slider
8
8
9
-
A draggable slider for continuous values. Supports vertical and horizontal orientations.
9
+
draggable slider for continuous values. Supports vertical and horizontal orientations.
10
10
11
11
## Basic usage
12
12
+5
-5
skills/opentui/docs/components/tab-select.mdx
+5
-5
skills/opentui/docs/components/tab-select.mdx
···
6
6
7
7
# TabSelect
8
8
9
-
Horizontal tab-based selection component with descriptions and scroll support. The component must be focused to receive keyboard input.
9
+
Horizontal tab-based selection component with descriptions and scroll support. component must be focused to receive keyboard input.
10
10
11
11
## Basic Usage
12
12
···
59
59
60
60
## Keyboard Navigation
61
61
62
-
When focused, the tab select responds to these keys:
62
+
When focused, tab select responds to these keys:
63
63
64
64
| Key | Action |
65
65
| ------------- | -------------------- |
···
71
71
72
72
### Item Selected
73
73
74
-
Emitted when the user presses Enter on a tab:
74
+
Emitted when user presses Enter on tab:
75
75
76
76
```typescript
77
77
import { TabSelectRenderableEvents, type TabSelectOption } from "@opentui/core"
···
84
84
85
85
### Selection Changed
86
86
87
-
Emitted when the highlighted tab changes:
87
+
Emitted when highlighted tab changes:
88
88
89
89
```typescript
90
90
import { TabSelectRenderableEvents, type TabSelectOption } from "@opentui/core"
···
200
200
201
201
## Scroll Behavior
202
202
203
-
When there are more tabs than fit in the width, the component automatically handles horizontal scrolling as you navigate with the keyboard.
203
+
When there're more tabs than fit in width, component automatically handles horizontal scrolling as you navigate with keyboard.
+3
-3
skills/opentui/docs/components/text.mdx
+3
-3
skills/opentui/docs/components/text.mdx
···
3
3
description: Display styled text content
4
4
order: 1
5
5
skill:
6
-
entry: true
7
-
intents: [text, styling, content, selection]
6
+
entry: true
7
+
intents: [text, styling, content, selection]
8
8
---
9
9
10
10
# Text
···
74
74
75
75
## Template literals for rich text
76
76
77
-
Use the `t` template literal for inline styling within a single text element:
77
+
Use `t` template literal for inline styling within single text element:
78
78
79
79
```typescript
80
80
import { TextRenderable, t, bold, underline, fg, bg, italic } from "@opentui/core"
+5
-5
skills/opentui/docs/components/textarea.mdx
+5
-5
skills/opentui/docs/components/textarea.mdx
···
34
34
35
35
## Submit handling
36
36
37
-
Bind a submit action and listen for `onSubmit`:
37
+
Bind submit action and listen for `onSubmit`:
38
38
39
39
```typescript
40
40
import { TextareaRenderable } from "@opentui/core"
···
101
101
102
102
## Cursor and selection control
103
103
104
-
`TextareaRenderable` (and its base `EditBufferRenderable`) exposes a programmatic API. You can move the cursor, edit text, and drive selections from your own keybindings or commands. All selection-aware movement methods accept `{ select: true }` to extend the current selection instead of moving the cursor.
104
+
`TextareaRenderable` (and its base `EditBufferRenderable`) exposes programmatic API. move cursor, edit text, and drive selections from your own keybindings or commands. All selection-aware movement methods accept `{ select: true }` to extend current selection instead of moving cursor.
105
105
106
106
### Cursor movement
107
107
···
153
153
textarea.redo()
154
154
```
155
155
156
-
These methods update the cursor, clear any active global selection, and call `requestRender()` for you.
156
+
These methods update cursor, clear any active global selection, and call `requestRender()` for you.
157
157
158
158
## Traits
159
159
160
-
The `traits` property lets an editor advertise intent to a host UI — which built-in keys it wants to capture, whether it wants the chrome to visually suspend, and a short status label for a footer or status bar. Assigning a new `EditorTraits` object emits the `traits-changed` event when the value differs from the previous one.
160
+
`traits` property lets editor advertise intent to host UI — which built-in keys it wants to capture, whether it wants chrome to visually suspend, and short status label for footer or status bar. Assigning new `EditorTraits` object emits `traits-changed` event when value differs from previous one.
161
161
162
162
```typescript
163
163
import { EditBufferRenderableEvents, type EditorTraits } from "@opentui/core"
···
179
179
| `suspend` | `boolean` | Hint to the host to suspend ambient UI (dim borders, hide hints, etc.) |
180
180
| `status` | `string` | Optional short label surfacing editor mode in a status bar |
181
181
182
-
Traits reset to an empty object when you destroy the renderable. Use `isEditBufferRenderable(renderable)` if you need to distinguish editor renderables from plain text renderables in a generic tree.
182
+
Traits reset to empty object when you destroy renderable. Use `isEditBufferRenderable(renderable)` if need to distinguish editor renderables from plain text renderables in generic tree.
+18
-18
skills/opentui/docs/core-concepts/colors.mdx
+18
-18
skills/opentui/docs/core-concepts/colors.mdx
···
6
6
7
7
# Colors
8
8
9
-
OpenTUI uses the `RGBA` class for color representation. The class stores 8-bit RGBA channel values plus packed metadata internally, but provides methods for working with different color formats.
9
+
OpenTUI uses `RGBA` class for color representation. class stores 8-bit RGBA channel values plus packed metadata internally, but provides methods for working with different color formats.
10
10
11
-
Every color also carries **color intent** inside the packed value: an RGB snapshot, an indexed ANSI slot, or the terminal default. The renderer uses this intent to keep palette-relative colors stable when the terminal palette changes.
11
+
Every color also carries **color intent** inside packed value: RGB snapshot, indexed ANSI slot, or terminal default. renderer uses this intent to keep palette-relative colors stable when terminal palette changes.
12
12
13
13
## Creating colors
14
14
···
60
60
61
61
## The parseColor utility
62
62
63
-
The `parseColor()` function converts various color formats to RGBA:
63
+
`parseColor()` function converts various color formats to RGBA:
64
64
65
65
```typescript
66
66
import { parseColor } from "@opentui/core"
···
73
73
74
74
## Color intent
75
75
76
-
Every `RGBA` value stores intent in packed metadata next to the RGBA snapshot. The renderer reads this intent to decide which ANSI sequence to emit:
76
+
Every `RGBA` value stores intent in packed metadata next to RGBA snapshot. renderer reads this intent to decide which ANSI sequence to emit:
77
77
78
-
- `rgb`: a literal RGB color. The renderer emits `38;2;r;g;b` / `48;2;r;g;b`.
79
-
- `default`: the terminal's default foreground or background. The renderer emits `39` / `49` (SGR default) so the terminal picks the right side of its palette.
80
-
- `indexed`: an indexed ANSI color. The renderer emits `38;5;n` / `48;5;n` so the user's theme overrides for that palette slot keep working when the palette changes.
78
+
- `rgb`: literal RGB color. renderer emits `38;2;r;g;b` / `48;2;r;g;b`.
79
+
- `default`: terminal's default foreground or background. renderer emits `39` / `49` (SGR default) so terminal picks right side of its palette.
80
+
- `indexed`: indexed ANSI color. renderer emits `38;5;n` / `48;5;n` so user's theme overrides for that palette slot keep working when palette changes.
81
81
82
-
Each color still carries its RGBA values so alpha blending and non-ANSI renderers work. The intent flows end-to-end through TypeScript, the FFI, the buffer, and the native renderer.
82
+
Each color still carries its RGBA values so alpha blending and non-ANSI renderers work. intent flows end-to-end through TypeScript, FFI, buffer, and native renderer.
83
83
84
84
### Default foreground and background
85
85
···
91
91
const bg = RGBA.defaultBackground()
92
92
```
93
93
94
-
You can pass an optional snapshot color to override the RGBA fallback. The renderer uses the snapshot for early frames, before it detects the terminal palette:
94
+
pass optional snapshot color to override RGBA fallback. renderer uses snapshot for early frames, before it detects terminal palette:
95
95
96
96
```typescript
97
97
const fg = RGBA.defaultForeground("#E6EDF3")
···
142
142
143
143
## Packed transport
144
144
145
-
`RGBA.buffer` is a `Uint16Array(4)`. The low byte of each component stores `r`, `g`, `b`, and `a`; the high bytes together store 32 bits of metadata.
145
+
`RGBA.buffer` is `Uint16Array(4)`. low byte of each component stores `r`, `g`, `b`, and `a`; high bytes together store 32 bits of metadata.
146
146
147
147
```typescript
148
148
const color = RGBA.fromIndex(6)
···
152
152
color.slot // 6
153
153
```
154
154
155
-
This lets native buffers compare current and next frame colors with exact integer equality. It also keeps palette intent attached to the color as it crosses the TypeScript/native boundary.
155
+
This lets native buffers compare current and next frame colors with exact integer equality. It also keeps palette intent attached to color as it crosses TypeScript/native boundary.
156
156
157
157
## Terminal palette detection
158
158
159
-
When the terminal supports it, the renderer queries the active palette (OSC 4 for palette slots, OSC 10/11 for default fg/bg, plus other special colors where supported). Indexed colors stay mapped to the terminal's user-configured slots, default colors stay linked to the terminal defaults, and non-truecolor renderers can re-resolve RGB fallbacks against the detected palette.
159
+
When terminal supports it, renderer queries active palette (OSC 4 for palette slots, OSC 10/11 for default fg/bg, plus other special colors where supported). Indexed colors stay mapped to terminal's user-configured slots, default colors stay linked to terminal defaults, and non-truecolor renderers can re-resolve RGB fallbacks against detected palette.
160
160
161
161
```typescript
162
162
const colors = await renderer.getPalette({ size: 256 })
···
167
167
168
168
Useful members:
169
169
170
-
- `renderer.getPalette(options?)` — returns a `TerminalColors` snapshot. Cached by requested size (`16` or `256`).
170
+
- `renderer.getPalette(options?)` — returns `TerminalColors` snapshot. Cached by requested size (`16` or `256`).
171
171
- `renderer.paletteDetectionStatus` — `"idle" | "detecting" | "cached"`.
172
-
- `renderer.clearPaletteCache()` — drop cached palettes (for example, after the user changes their theme).
173
-
- `renderer.on("palette", handler)` — subscribe to refreshed palette snapshots when the detected palette changes.
172
+
- `renderer.clearPaletteCache()` — drop cached palettes (for example, after user changes their theme).
173
+
- `renderer.on("palette", handler)` — subscribe to refreshed palette snapshots when detected palette changes.
174
174
175
-
`getPalette` throws if the renderer is suspended. Startup palette detection runs automatically only when native ANSI-256 fallback rendering needs palette data (`ansi256` without truecolor `rgb`). Truecolor terminals query the palette only when you call `getPalette()` or when a palette listener exists and the terminal reports a theme change.
175
+
`getPalette` throws if renderer is suspended. Startup palette detection runs automatically only when native ANSI-256 fallback rendering needs palette data (`ansi256` without truecolor `rgb`). Truecolor terminals query palette only when you call `getPalette()` or when palette listener exists and terminal reports theme change.
176
176
177
177
## Alpha blending
178
178
179
-
You can use transparent cells and alpha blending for layered effects:
179
+
use transparent cells and alpha blending for layered effects:
180
180
181
181
```typescript
182
182
import { FrameBufferRenderable, RGBA } from "@opentui/core"
···
193
193
canvas.frameBuffer.setCellWithAlphaBlending(10, 5, " ", transparent, semiTransparent)
194
194
```
195
195
196
-
Blended colors become literal RGB colors internally. This is intentional: once colors are blended, the result no longer represents a specific ANSI slot or terminal default.
196
+
Blended colors become literal RGB colors internally. This is intentional: once colors are blended, result no longer represents specific ANSI slot or terminal default.
197
197
198
198
## Text attributes with colors
199
199
+7
-7
skills/opentui/docs/core-concepts/console.mdx
+7
-7
skills/opentui/docs/core-concepts/console.mdx
···
6
6
7
7
# Console overlay
8
8
9
-
OpenTUI includes a built-in console overlay that captures all `console.log`, `console.info`, `console.warn`, `console.error`, and `console.debug` calls. You can position the console at any edge of the terminal. It supports scrolling and focus management.
9
+
OpenTUI includes built-in console overlay that captures all `console.log`, `console.info`, `console.warn`, `console.error`, and `console.debug` calls. position console at any edge of terminal. It supports scrolling and focus management.
10
10
11
11
## Basic usage
12
12
···
54
54
55
55
## Toggling the console
56
56
57
-
Toggle the console overlay in code:
57
+
Toggle console overlay in code:
58
58
59
59
```typescript
60
60
// Toggle visibility and focus
···
66
66
67
67
## Console shortcuts
68
68
69
-
When the console is focused:
69
+
When console is focused:
70
70
71
71
| Key | Action |
72
72
| ---------- | -------------------------- |
···
76
76
77
77
## Keybinding for toggle
78
78
79
-
Add a keyboard shortcut to toggle the console:
79
+
Add keyboard shortcut to toggle console:
80
80
81
81
```typescript
82
82
renderer.keyInput.on("keypress", (key) => {
···
94
94
95
95
## Why use the console?
96
96
97
-
Terminal UI applications capture stdout for rendering. Regular `console.log` calls would interfere with your interface. The console overlay solves this problem:
97
+
Terminal UI applications capture stdout for rendering. Regular `console.log` calls would interfere with your interface. console overlay solves this problem:
98
98
99
-
- Captures all console output without disrupting the UI
100
-
- Displays logs in a dedicated overlay area
99
+
- Captures all console output without disrupting UI
100
+
- Displays logs in dedicated overlay area
101
101
- Color-codes different log levels for easy identification
102
102
- Lets you scroll through history for debugging
103
103
+11
-11
skills/opentui/docs/core-concepts/constructs.mdx
+11
-11
skills/opentui/docs/core-concepts/constructs.mdx
···
6
6
7
7
# Constructs
8
8
9
-
Constructs let you compose your UI in a declarative, React-like way. They are factory functions that create VNodes (virtual nodes). A VNode is a lightweight description of a component. When you add a VNode to the tree, it becomes an actual Renderable.
9
+
Constructs let you compose your UI in declarative, React-like way. They are factory functions that create VNodes (virtual nodes). VNode is lightweight description of component. When you add VNode to tree, it becomes actual Renderable.
10
10
11
11
## Basic Usage
12
12
···
26
26
)
27
27
```
28
28
29
-
Pass children as additional arguments after the props object, not as a property.
29
+
Pass children as additional arguments after props object, not as property.
30
30
31
31
## Available Constructs
32
32
···
62
62
63
63
## How Constructs Work
64
64
65
-
When you call a construct like `Box()`, it creates a VNode - a plain object describing what to create:
65
+
When you call construct like `Box()`, it creates VNode - plain object describing what to create:
66
66
67
67
```typescript
68
68
// This creates a VNode, not an actual BoxRenderable
···
74
74
75
75
This deferred creation lets you:
76
76
77
-
- Compose UI without a render context
78
-
- Queue method calls before the component exists
77
+
- Compose UI without render context
78
+
- Queue method calls before component exists
79
79
- Write cleaner, more declarative code
80
80
81
81
## Creating Custom Constructs
···
102
102
103
103
## Method Chaining on VNodes
104
104
105
-
VNodes support method calls. The system queues these calls and applies them after creating the component:
105
+
VNodes support method calls. system queues these calls and applies them after creating component:
106
106
107
107
```typescript
108
108
const input = Input({ id: "my-input", placeholder: "Type here..." })
···
114
114
renderer.root.add(input)
115
115
```
116
116
117
-
You can also set properties:
117
+
also set properties:
118
118
119
119
```typescript
120
120
const box = Box({ id: "my-box" })
···
124
124
125
125
## The delegate() Function
126
126
127
-
Composite components often need outer method calls to reach a specific inner component. The `delegate()` function maps method and property names to descendant IDs:
127
+
Composite components often need outer method calls to reach specific inner component. `delegate()` function maps method and property names to descendant IDs:
128
128
129
129
```typescript
130
130
import { delegate, Box, Text, Input } from "@opentui/core"
···
157
157
158
158
### Delegate Mappings
159
159
160
-
The mapping object's keys are method or property names, and the values are descendant IDs:
160
+
mapping object's keys are method or property names, and values are descendant IDs:
161
161
162
162
```typescript
163
163
delegate(
···
189
189
190
190
## Mixing Renderables and Constructs
191
191
192
-
You can mix both approaches:
192
+
mix both approaches:
193
193
194
194
```typescript
195
195
import { BoxRenderable, Text, Input } from "@opentui/core"
···
223
223
224
224
## Next Steps
225
225
226
-
See [Renderables vs Constructs](/docs/core-concepts/renderables-vs-constructs) for a detailed comparison of when to use each approach.
226
+
See [Renderables vs Constructs](/docs/core-concepts/renderables-vs-constructs) for detailed comparison of when to use each approach.
+11
-11
skills/opentui/docs/core-concepts/keyboard.mdx
+11
-11
skills/opentui/docs/core-concepts/keyboard.mdx
···
3
3
description: Handling keyboard events in OpenTUI
4
4
order: 6
5
5
skill:
6
-
entry: true
7
-
intents: [keyboard, input, keybindings, paste, focus]
6
+
entry: true
7
+
intents: [keyboard, input, keybindings, paste, focus]
8
8
---
9
9
10
10
# Keyboard input
11
11
12
-
OpenTUI parses terminal input and provides structured key events. The `renderer.keyInput` EventEmitter emits `keypress` events plus raw `paste` events with optional metadata.
12
+
OpenTUI parses terminal input and provides structured key events. `renderer.keyInput` EventEmitter emits `keypress` events plus raw `paste` events with optional metadata.
13
13
14
14
## Basic key handling
15
15
···
44
44
45
45
## Key aliases
46
46
47
-
OpenTUI normalizes several key names so your keybindings work the same across layouts and input paths. OpenTUI applies aliases after the parser reports a key, before emitting `keypress`.
47
+
OpenTUI normalizes several key names so your keybindings work same across layouts and input paths. OpenTUI applies aliases after parser reports key, before emitting `keypress`.
48
48
49
-
The default aliases are:
49
+
default aliases are:
50
50
51
51
```ts
52
52
// enter -> return
···
60
60
// kpdecimal/kpdivide/kpmultiply/kpminus/kpplus/kpequal/kpseparator -> symbols
61
61
```
62
62
63
-
Both `key.name === "enter"` and `key.name === "kpenter"` resolve to `"return"` when you match them with `matchesKeyBinding`. Editable components that accept a `keyAliasMap` option (`InputRenderable`, `TextareaRenderable`, `SelectRenderable`, etc.) merge these defaults with your own map:
63
+
Both `key.name === "enter"` and `key.name === "kpenter"` resolve to `"return"` when you match them with `matchesKeyBinding`. Editable components that accept `keyAliasMap` option (`InputRenderable`, `TextareaRenderable`, `SelectRenderable`, etc.) merge these defaults with your own map:
64
64
65
65
```typescript
66
66
import { InputRenderable } from "@opentui/core"
···
174
174
175
175
## Exit on Ctrl+C
176
176
177
-
Configure the renderer to automatically exit on Ctrl+C:
177
+
Configure renderer to automatically exit on Ctrl+C:
178
178
179
179
```typescript
180
180
const renderer = await createCliRenderer({
···
197
197
198
198
## Kitty keyboard protocol
199
199
200
-
OpenTUI opts into the [kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/) when the terminal supports it. The protocol gives more reliable key names and modifier state than legacy input encoding, including release events, disambiguated escape, alt+key sequences, and alternate keys for cross-layout shortcuts. Configure it with the `useKittyKeyboard` option:
200
+
OpenTUI opts into [kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/) when terminal supports it. protocol gives more reliable key names and modifier state than legacy input encoding, including release events, disambiguated escape, alt+key sequences, and alternate keys for cross-layout shortcuts. Configure it with `useKittyKeyboard` option:
201
201
202
202
```typescript
203
203
const renderer = await createCliRenderer({
···
222
222
| `allKeysAsEscapes` | `false` | `REPORT_ALL_KEYS_AS_ESCAPE_CODES` | Encode every key as an escape sequence |
223
223
| `reportText` | `false` | `REPORT_ASSOCIATED_TEXT` | Include the text a key press generates |
224
224
225
-
`events: true` enables the `keyrelease` event on `renderer.keyInput` as well as `eventType` on `KeyEvent`.
225
+
`events: true` enables `keyrelease` event on `renderer.keyInput` as well as `eventType` on `KeyEvent`.
226
226
227
-
`useKittyKeyboard: {}` applies the defaults (`disambiguate` + `alternateKeys`). Passing `null` disables the protocol entirely.
227
+
`useKittyKeyboard: {}` applies defaults (`disambiguate` + `alternateKeys`). Passing `null` disables protocol entirely.
228
228
229
229
## Focus and key routing
230
230
231
-
Focus components to receive keyboard input. OpenTUI routes events to the focused component:
231
+
Focus components to receive keyboard input. OpenTUI routes events to focused component:
232
232
233
233
```typescript
234
234
import { InputRenderable } from "@opentui/core"
+9
-9
skills/opentui/docs/core-concepts/layout.mdx
+9
-9
skills/opentui/docs/core-concepts/layout.mdx
···
3
3
description: Flexible positioning and sizing with Yoga/Flexbox
4
4
order: 5
5
5
skill:
6
-
entry: true
7
-
intents: [layout, flexbox, yoga, positioning]
6
+
entry: true
7
+
intents: [layout, flexbox, yoga, positioning]
8
8
---
9
9
10
10
# Layout System
11
11
12
-
OpenTUI uses the Yoga layout engine to provide CSS Flexbox-like capabilities for responsive terminal layouts. You can create complex, dynamic interfaces that adapt to terminal size changes.
12
+
OpenTUI uses Yoga layout engine to provide CSS Flexbox-like capabilities for responsive terminal layouts. create complex, dynamic interfaces that adapt to terminal size changes.
13
13
14
14
## Flexbox Basics
15
15
16
-
The layout system supports standard flexbox properties:
16
+
layout system supports standard flexbox properties:
17
17
18
18
```typescript
19
19
import { BoxRenderable, createCliRenderer } from "@opentui/core"
···
50
50
51
51
## Flex Direction
52
52
53
-
Control the direction of child elements:
53
+
Control direction of child elements:
54
54
55
55
```typescript
56
56
// Vertical layout (default)
···
74
74
75
75
## Justify Content
76
76
77
-
Align children along the main axis:
77
+
Align children along main axis:
78
78
79
79
```typescript
80
80
{
···
99
99
100
100
## Align Items
101
101
102
-
Align children along the cross axis:
102
+
Align children along cross axis:
103
103
104
104
```typescript
105
105
{
···
153
153
154
154
### Relative (Default)
155
155
156
-
Elements flow normally in the layout:
156
+
Elements flow normally in layout:
157
157
158
158
```typescript
159
159
{
···
205
205
206
206
## Using Constructs
207
207
208
-
The same layout properties work with the declarative API:
208
+
same layout properties work with declarative API:
209
209
210
210
```typescript
211
211
import { Box, Text } from "@opentui/core"
+12
-12
skills/opentui/docs/core-concepts/lifecycle.mdx
+12
-12
skills/opentui/docs/core-concepts/lifecycle.mdx
···
6
6
7
7
# Lifecycle and cleanup
8
8
9
-
OpenTUI gives you control over terminal cleanup. Call `renderer.destroy()` when you shut down. It restores the terminal to its original state, and it frees resources.
9
+
OpenTUI gives you control over terminal cleanup. Call `renderer.destroy()` when you shut down. It restores terminal to its original state, and it frees resources.
10
10
11
11
## Why you must handle cleanup
12
12
13
13
OpenTUI does not automatically clean up on `process.exit` or unhandled errors. This design gives you more control over shutdown behavior:
14
14
15
-
- You may want to handle errors and keep running
16
-
- You may use effect systems, like Effect.ts, with their own shutdown handling
17
-
- You may need custom cleanup order or additional shutdown logic
15
+
- want to handle errors and keep running
16
+
- use effect systems, like Effect.ts, with their own shutdown handling
17
+
- need custom cleanup order or additional shutdown logic
18
18
19
19
## Use `renderer.destroy()`
20
20
···
31
31
renderer.destroy()
32
32
```
33
33
34
-
For reliable cleanup, keep renderer teardown in the same control flow as your app startup:
34
+
For reliable cleanup, keep renderer teardown in same control flow as your app startup:
35
35
36
36
```typescript
37
37
import { createCliRenderer } from "@opentui/core"
···
67
67
| `SIGPIPE` | Broken pipe |
68
68
| `SIGBUS` | Bus error |
69
69
70
-
You can customize which signals trigger cleanup:
70
+
customize which signals trigger cleanup:
71
71
72
72
```typescript
73
73
// Only handle SIGINT and SIGTERM
···
83
83
84
84
## Ctrl+C behavior
85
85
86
-
By default, Ctrl+C calls `destroy()`. If you want to handle Ctrl+C yourself, disable the internal handler and remove `SIGINT` from `exitSignals`:
86
+
By default, Ctrl+C calls `destroy()`. If want to handle Ctrl+C yourself, disable internal handler and remove `SIGINT` from `exitSignals`:
87
87
88
88
```typescript
89
89
const renderer = await createCliRenderer({
···
101
101
102
102
## Destroy callback
103
103
104
-
Run custom logic when the renderer is destroyed:
104
+
Run custom logic when renderer is destroyed:
105
105
106
106
```typescript
107
107
const renderer = await createCliRenderer({
···
113
113
114
114
## What `destroy()` cleans up
115
115
116
-
The `destroy()` method cleans up these resources:
116
+
`destroy()` method cleans up these resources:
117
117
118
-
- Removes the signal and process listeners that OpenTUI adds
118
+
- Removes signal and process listeners that OpenTUI adds
119
119
- Clears timers and render loops
120
-
- Destroys all renderables in the tree
120
+
- Destroys all renderables in tree
121
121
- Restores stdin raw mode
122
122
- Resets terminal state (cursor, alternate screen, etc.)
123
123
- Frees native resources
124
124
125
125
## Troubleshooting
126
126
127
-
If your terminal stays in a broken state after a crash:
127
+
If your terminal stays in broken state after crash:
128
128
129
129
1. Run `reset` in your terminal to restore it
130
130
2. Add `uncaughtException` and `unhandledRejection` handlers to your app
+7
-7
skills/opentui/docs/core-concepts/renderables-vs-constructs.mdx
+7
-7
skills/opentui/docs/core-concepts/renderables-vs-constructs.mdx
···
6
6
7
7
# Renderables vs Constructs
8
8
9
-
OpenTUI provides two ways to build your UI: the imperative Renderable API and the declarative Construct API. Both approaches have different tradeoffs.
9
+
OpenTUI provides two ways to build your UI: imperative Renderable API and declarative Construct API. Both approaches have different tradeoffs.
10
10
11
11
## Imperative (Renderables)
12
12
13
-
You create `Renderable` instances with a `RenderContext` and compose them using `add()`. You mutate state and behavior directly on instances through setters and methods.
13
+
You create `Renderable` instances with `RenderContext` and compose them using `add()`. You mutate state and behavior directly on instances through setters and methods.
14
14
15
15
```typescript
16
16
import { BoxRenderable, TextRenderable, InputRenderable, createCliRenderer, type RenderContext } from "@opentui/core"
···
71
71
72
72
## Declarative (Constructs)
73
73
74
-
Builds a lightweight VNode graph using functional constructs. Instances don't exist until you add the node to the tree. VNodes queue method calls and replay them when instantiated.
74
+
Builds lightweight VNode graph using functional constructs. Instances don't exist until you add node to tree. VNodes queue method calls and replay them when instantiated.
75
75
76
76
```typescript
77
77
import { Text, Input, Box, createCliRenderer, delegate } from "@opentui/core"
···
124
124
125
125
## The delegate() function
126
126
127
-
The `delegate()` function makes constructs ergonomic by routing method calls from the parent to specific children:
127
+
`delegate()` function makes constructs ergonomic by routing method calls from parent to specific children:
128
128
129
129
```typescript
130
130
function Button(props: { id: string; label: string; onClick: () => void }) {
···
153
153
154
154
- You need fine-grained control over component lifecycle
155
155
- You're building low-level custom components
156
-
- You need to access renderable methods immediately
157
-
- Performance is critical and you want to avoid VNode overhead
156
+
- need to access renderable methods immediately
157
+
- Performance is critical and want to avoid VNode overhead
158
158
159
159
### Use Constructs when
160
160
···
165
165
166
166
## Mixing both
167
167
168
-
You can mix both approaches in the same application:
168
+
mix both approaches in same application:
169
169
170
170
```typescript
171
171
import { BoxRenderable, Text, Input } from "@opentui/core"
+17
-17
skills/opentui/docs/core-concepts/renderables.mdx
+17
-17
skills/opentui/docs/core-concepts/renderables.mdx
···
1
1
---
2
2
title: Renderables
3
-
description: The building blocks of your terminal UI
3
+
description: building blocks of your terminal UI
4
4
order: 2
5
5
---
6
6
7
7
# Renderables
8
8
9
-
Renderables are the building blocks of your UI. You can position, style, and nest them within each other. Each renderable represents a visual element and uses the Yoga layout engine for flexible positioning and sizing.
9
+
Renderables are building blocks of your UI. position, style, and nest them within each other. Each renderable represents visual element and uses Yoga layout engine for flexible positioning and sizing.
10
10
11
11
## Creating Renderables
12
12
13
-
Create a renderable by instantiating a class with a render context (the renderer) and options:
13
+
Create renderable by instantiating class with render context ( renderer) and options:
14
14
15
15
```typescript
16
16
import { createCliRenderer, TextRenderable, BoxRenderable } from "@opentui/core"
···
50
50
51
51
## The Renderable Tree
52
52
53
-
Renderables form a tree structure. Use `add()` and `remove()` to manage children:
53
+
Renderables form tree structure. Use `add()` and `remove()` to manage children:
54
54
55
55
```typescript
56
56
const container = new BoxRenderable(renderer, {
···
73
73
74
74
## Finding Renderables
75
75
76
-
Navigate the tree to find specific renderables:
76
+
Navigate tree to find specific renderables:
77
77
78
78
```typescript
79
79
// Get a direct child by ID
···
119
119
})
120
120
```
121
121
122
-
See the [Layout](/docs/core-concepts/layout) page for complete details.
122
+
See [Layout](/docs/core-concepts/layout) page for complete details.
123
123
124
124
## Focus Management
125
125
···
143
143
console.log(input.focused) // true
144
144
```
145
145
146
-
By default, left-clicking a renderable will auto-focus the closest focusable ancestor. Disable this globally with
146
+
By default, left-clicking renderable will auto-focus closest focusable ancestor. Disable this globally with
147
147
`createCliRenderer({ autoFocus: false })`, or stop it per interaction by calling `event.preventDefault()` in
148
148
`onMouseDown`.
149
149
···
163
163
164
164
### Focused descendants
165
165
166
-
A renderable can also react to focus living inside one of its descendants through the `hasFocusedDescendant` flag. When any child has focus, every ancestor's `hasFocusedDescendant` flips to `true` and OpenTUI marks them dirty so they repaint. `BoxRenderable` uses this to paint the `focusedBorderColor` whenever the box itself is focusable and any descendant currently owns focus:
166
+
renderable can also react to focus living inside one of its descendants through `hasFocusedDescendant` flag. When any child has focus, every ancestor's `hasFocusedDescendant` flips to `true` and OpenTUI marks them dirty so they repaint. `BoxRenderable` uses this to paint `focusedBorderColor` whenever box itself is focusable and any descendant currently owns focus:
167
167
168
168
```typescript
169
169
const panel = new BoxRenderable(renderer, {
···
212
212
- `onMouseScroll`
213
213
- `onMouse` (catch-all)
214
214
215
-
Mouse events bubble up through the tree. Stop propagation with `event.stopPropagation()`.
215
+
Mouse events bubble up through tree. Stop propagation with `event.stopPropagation()`.
216
216
217
217
### Keyboard Events
218
218
···
236
236
237
237
## Visibility
238
238
239
-
Control visibility with the `visible` property:
239
+
Control visibility with `visible` property:
240
240
241
241
```typescript
242
242
// Hide (also removes from layout)
···
246
246
panel.visible = true
247
247
```
248
248
249
-
When `visible` is `false`, Yoga excludes the renderable from layout calculation (equivalent to CSS `display: none`).
249
+
When `visible` is `false`, Yoga excludes renderable from layout calculation (equivalent to CSS `display: none`).
250
250
251
251
## Opacity
252
252
···
256
256
panel.opacity = 0.5 // 50% transparent
257
257
```
258
258
259
-
Opacity affects the renderable and all its children.
259
+
Opacity affects renderable and all its children.
260
260
261
261
## Z-Index
262
262
···
272
272
273
273
## Live Rendering
274
274
275
-
For animations, extend the Renderable class and override `onUpdate`:
275
+
For animations, extend Renderable class and override `onUpdate`:
276
276
277
277
```typescript
278
278
class AnimatedBox extends BoxRenderable {
···
290
290
291
291
## Translation
292
292
293
-
Offset a renderable from its layout position (useful for scrolling/animation):
293
+
Offset renderable from its layout position (useful for scrolling/animation):
294
294
295
295
```typescript
296
296
// Offset by pixels
···
298
298
renderable.translateY = -5
299
299
```
300
300
301
-
This moves the renderable visually without affecting layout.
301
+
This moves renderable visually without affecting layout.
302
302
303
303
## Buffered Rendering
304
304
305
-
Enable offscreen rendering for complex content and use hooks to draw to the buffer:
305
+
Enable offscreen rendering for complex content and use hooks to draw to buffer:
306
306
307
307
```typescript
308
308
import { RGBA } from "@opentui/core"
···
347
347
348
348
## Destroying Renderables
349
349
350
-
Clean up a renderable and remove it from the tree:
350
+
Clean up renderable and remove it from tree:
351
351
352
352
```typescript
353
353
// Remove from parent and free resources
+63
-64
skills/opentui/docs/core-concepts/renderer.mdx
+63
-64
skills/opentui/docs/core-concepts/renderer.mdx
···
1
1
---
2
2
title: Renderer
3
-
description: CliRenderer manages terminal output and the render loop
3
+
description: CliRenderer manages terminal output and render loop
4
4
order: 1
5
5
skill:
6
-
entry: true
7
-
intents: [core, renderer, terminal, scrollback, lifecycle]
6
+
entry: true
7
+
intents: [core, renderer, terminal, scrollback, lifecycle]
8
8
---
9
9
10
10
# Renderer
11
11
12
-
The `CliRenderer` drives OpenTUI. It manages terminal output, handles input events, runs the rendering loop, and provides context for creating renderables.
12
+
`CliRenderer` drives OpenTUI. It manages terminal output, handles input events, runs rendering loop, and provides context for creating renderables.
13
13
14
14
## Creating a renderer
15
15
16
-
Create a renderer with the async factory function:
16
+
Create renderer with async factory function:
17
17
18
18
```typescript
19
19
import { createCliRenderer } from "@opentui/core"
···
24
24
})
25
25
```
26
26
27
-
The factory function does three things:
27
+
factory function does three things:
28
28
29
-
1. Loads the native Zig rendering library
30
-
2. Configures terminal settings (mouse, keyboard protocol, and the selected screen mode)
31
-
3. Returns an initialized `CliRenderer` instance
29
+
1. Loads native Zig rendering library
30
+
2. Configures terminal settings (mouse, keyboard protocol, and selected screen mode)
31
+
3. Returns initialized `CliRenderer` instance
32
32
33
33
## Configuration options
34
34
35
-
This page covers the options that most apps set directly.
35
+
This page covers options that most apps set directly.
36
36
`CliRendererConfig` also includes lower-level hooks for testing and tuning, such as `stdin`, `stdout`, `clock`,
37
37
`postProcessFns`, and `prependInputHandlers`.
38
38
···
56
56
| `openConsoleOnError` | `boolean` | `true` (dev) | Open the console overlay on uncaught errors |
57
57
| `onDestroy` | `() => void` | - | Run after the renderer finishes cleanup |
58
58
59
-
You can also change `screenMode`, `footerHeight`, `externalOutputMode`, and `consoleMode` at runtime through their
59
+
also change `screenMode`, `footerHeight`, `externalOutputMode`, and `consoleMode` at runtime through their
60
60
matching `renderer` properties.
61
61
62
62
## Screen modes
63
63
64
-
The `screenMode` option controls whether OpenTUI owns the alternate screen or a reserved region of the main screen. You
64
+
`screenMode` option controls whether OpenTUI owns alternate screen or reserved region of main screen. You
65
65
can also change modes at runtime by setting `renderer.screenMode`.
66
66
67
67
### `"alternate-screen"` (default)
68
68
69
-
Switches to the terminal's alternate screen buffer. The original scrollback content is preserved and restored when the
70
-
renderer exits. This is the standard mode for full-screen TUI applications.
69
+
Switches to terminal's alternate screen buffer. original scrollback content is preserved and restored when renderer exits. This is standard mode for full-screen TUI applications.
71
70
72
71
```typescript
73
72
const renderer = await createCliRenderer({
···
77
76
78
77
### `"main-screen"`
79
78
80
-
Renders on the terminal's main screen without switching buffers. OpenTUI still reserves a render region by scrolling terminal content, so this is not a true scrollback-native inline or direct renderer. Use it when you want the UI to stay on the main screen for testing, benchmarks, or short-lived tools.
79
+
Renders on terminal's main screen without switching buffers. OpenTUI still reserves render region by scrolling terminal content, so this is not true scrollback-native inline or direct renderer. Use it when you want UI to stay on main screen for testing, benchmarks, or short-lived tools.
81
80
82
81
```typescript
83
82
const renderer = await createCliRenderer({
···
87
86
88
87
### `"split-footer"`
89
88
90
-
Pins the renderer to a reserved footer region at the bottom of the terminal. The area above the footer stays available for normal program output. This is the closest thing OpenTUI currently has to a direct-render mode, but it still uses the same buffered main-screen renderer rather than a separate inline backend.
89
+
Pins renderer to reserved footer region at bottom of terminal. area above footer stays available for normal program output. This is closest thing OpenTUI currently has to direct-render mode, but it still uses same buffered main-screen renderer rather than separate inline backend.
91
90
92
-
The `footerHeight` option controls how many rows the footer requests (default: 12). When using split-footer mode, `externalOutputMode` defaults to `"capture-stdout"` so that writes to `stdout.write` can be replayed above the footer instead of overlapping it.
91
+
`footerHeight` option controls how many rows footer requests (default: 12). When using split-footer mode, `externalOutputMode` defaults to `"capture-stdout"` so that writes to `stdout.write` can be replayed above footer instead of overlapping it.
93
92
94
93
```typescript
95
94
const renderer = await createCliRenderer({
···
101
100
renderer.footerHeight = 15
102
101
```
103
102
104
-
Split-footer bookkeeping lives in the native renderer. A shared `SplitScrollback` model tracks the rows it has already published and the current tail column, so the footer pins to the bottom of the terminal as scrollback grows. Captured stdout and [scrollback writers](#writing-to-scrollback) both produce styled `OptimizedBuffer` snapshots. The native side emits these as ANSI alongside the footer repaint in one atomic frame. The renderer flushes pending output before `resize`, `suspend`, mode transitions, and `destroy`.
103
+
Split-footer bookkeeping lives in native renderer. shared `SplitScrollback` model tracks rows it has already published and current tail column, so footer pins to bottom of terminal as scrollback grows. Captured stdout and [scrollback writers](#writing-to-scrollback) both produce styled `OptimizedBuffer` snapshots. native side emits these as ANSI alongside footer repaint in one atomic frame. renderer flushes pending output before `resize`, `suspend`, mode transitions, and `destroy`.
105
104
106
105
## External output mode
107
106
108
-
The `externalOutputMode` option controls what happens to writes that go through the renderer's configured `stdout.write` while the renderer is active. It does not change `stderr`, and it is separate from the built-in console overlay.
107
+
`externalOutputMode` option controls what happens to writes that go through renderer's configured `stdout.write` while renderer is active. It does not change `stderr`, and it's separate from built-in console overlay.
109
108
110
-
The native renderer still paints to the real TTY. `externalOutputMode` only changes the TypeScript-side `stdout.write` path.
109
+
native renderer still paints to real TTY. `externalOutputMode` only changes TypeScript-side `stdout.write` path.
111
110
112
-
- **`"capture-stdout"`**: Intercepts `stdout.write`, queues the text, and flushes it above the footer during split-footer renders. Only valid when `screenMode` is `"split-footer"`.
113
-
- **`"passthrough"`**: Leaves `stdout.write` untouched. Output goes directly to the terminal.
111
+
- **`"capture-stdout"`**: Intercepts `stdout.write`, queues text, and flushes it above footer during split-footer renders. Only valid when `screenMode` is `"split-footer"`.
112
+
- **`"passthrough"`**: Leaves `stdout.write` untouched. Output goes directly to terminal.
114
113
115
-
The default depends on the screen mode: `"capture-stdout"` for split-footer, `"passthrough"` for everything else.
114
+
default depends on screen mode: `"capture-stdout"` for split-footer, `"passthrough"` for everything else.
116
115
117
116
```typescript
118
117
// Captured stdout appears above the footer
···
127
126
128
127
## Console mode
129
128
130
-
The `consoleMode` option controls the built-in console overlay (`TerminalConsole`).
129
+
`consoleMode` option controls built-in console overlay (`TerminalConsole`).
131
130
132
-
- **`"console-overlay"`** (default): Captures console output (console.log, console.error, etc.) and renders it in a toggleable panel within the TUI.
133
-
- **`"disabled"`**: Hides and deactivates the overlay surface.
131
+
- **`"console-overlay"`** (default): Captures console output (console.log, console.error, etc.) and renders it in toggleable panel within TUI.
132
+
- **`"disabled"`**: Hides and deactivates overlay surface.
134
133
135
-
Current caveat: `consoleMode` only changes the overlay surface.
134
+
Current caveat: `consoleMode` only changes overlay surface.
136
135
If you need plain `console.*` behavior, set `OTUI_USE_CONSOLE=false`.
137
136
138
137
```typescript
···
145
144
146
145
## Writing to scrollback
147
146
148
-
In split-footer mode with `externalOutputMode: "capture-stdout"`, the renderer also owns a programmatic append path above the footer. Use it when you want rich, styled output in scrollback instead of raw `console.log` text — colors, wrapping, syntax-highlighted code, and markdown. Every append goes through the same FIFO queue as captured stdout, so ordering stays deterministic even when both sources interleave.
147
+
In split-footer mode with `externalOutputMode: "capture-stdout"`, renderer also owns programmatic append path above footer. Use it when you want rich, styled output in scrollback instead of raw `console.log` text — colors, wrapping, syntax-highlighted code, and markdown. Every append goes through same FIFO queue as captured stdout, so ordering stays deterministic even when both sources interleave.
149
148
150
149
Both APIs require `screenMode: "split-footer"` and `externalOutputMode: "capture-stdout"`. They throw otherwise.
151
150
152
151
### `renderer.writeToScrollback(writer)`
153
152
154
-
Render a renderable tree into an off-screen buffer and commit it as one scrollback snapshot.
153
+
Render renderable tree into off-screen buffer and commit it as one scrollback snapshot.
155
154
156
155
```typescript
157
156
import { TextRenderable } from "@opentui/core"
···
178
177
})
179
178
```
180
179
181
-
The writer receives a `ScrollbackRenderContext`:
180
+
writer receives `ScrollbackRenderContext`:
182
181
183
182
| Field | Type | Description |
184
183
| --------------- | --------------- | ------------------------------------------------------- |
···
187
186
| `tailColumn` | `number` | Column where the previous scrollback commit ended |
188
187
| `renderContext` | `RenderContext` | Context you pass to new renderables inside the snapshot |
189
188
190
-
And returns a `ScrollbackSnapshot`:
189
+
And returns `ScrollbackSnapshot`:
191
190
192
191
| Field | Type | Description |
193
192
| ----------------- | ------------ | -------------------------------------------------------------------------------------------- |
···
199
198
| `trailingNewline` | `boolean` | Append a newline after the final row of this commit (default: `true`) |
200
199
| `teardown` | `() => void` | Optional cleanup hook invoked after the snapshot is rendered (e.g., dispose a Solid subtree) |
201
200
202
-
Use `startOnNewLine: false` plus `trailingNewline: false` for inline output — for example, an icon prefix followed by streaming text.
201
+
Use `startOnNewLine: false` plus `trailingNewline: false` for inline output — for example, icon prefix followed by streaming text.
203
202
204
203
### `renderer.createScrollbackSurface(options?)`
205
204
206
-
For streaming output that you want to render many times before committing (token-by-token code highlighting, markdown blocks settling as they parse), use a `ScrollbackSurface`. The surface renders into a backing buffer. You can re-render the tree in place and then commit specific row ranges to scrollback.
205
+
For streaming output that want to render many times before committing (token-by-token code highlighting, markdown blocks settling as they parse), use `ScrollbackSurface`. surface renders into backing buffer. re-render tree in place and then commit specific row ranges to scrollback.
207
206
208
207
```typescript
209
208
const surface = renderer.createScrollbackSurface({ startOnNewLine: true })
···
236
235
| `commitRows(start, endExclusive, options?)` | Copy a row range out of the backing buffer and enqueue it as a scrollback commit |
237
236
| `destroy()` | Tear down the surface and its backing buffer |
238
237
239
-
`commitRows` throws if you call it before `render()`, or if the renderer's width or `widthMethod` changed since the last `render()`. Re-render before committing fresh rows in either case.
238
+
`commitRows` throws if you call it before `render()`, or if renderer's width or `widthMethod` changed since last `render()`. Re-render before committing fresh rows in either case.
240
239
241
-
For React and Solid, use the binding-level helpers that wrap `writeToScrollback` with JSX support. See [`createScrollbackWriter` / `writeSolidToScrollback`](/docs/bindings/solid#scrollback-writers) in the Solid docs.
240
+
For React and Solid, use binding-level helpers that wrap `writeToScrollback` with JSX support. See [`createScrollbackWriter` / `writeSolidToScrollback`](/docs/bindings/solid#scrollback-writers) in Solid docs.
242
241
243
242
## The root renderable
244
243
245
-
Every renderer has a `root` property. It is a special `RootRenderable` at the top of the component tree:
244
+
Every renderer has `root` property. it's special `RootRenderable` at top of component tree:
246
245
247
246
```typescript
248
247
import { Box, Text } from "@opentui/core"
···
251
250
renderer.root.add(Box({ width: 40, height: 10, borderStyle: "rounded" }, Text({ content: "Hello, OpenTUI!" })))
252
251
```
253
252
254
-
The root renderable fills the entire terminal and adjusts when you resize it.
253
+
root renderable fills entire terminal and adjusts when you resize it.
255
254
256
255
## Render loop control
257
256
258
-
You can use these control modes:
257
+
use these control modes:
259
258
260
259
### Automatic mode (default)
261
260
262
-
If you do not call `start()`, the renderer re-renders only when the component tree changes:
261
+
If you do not call `start()`, renderer re-renders only when component tree changes:
263
262
264
263
```typescript
265
264
const renderer = await createCliRenderer()
···
268
267
269
268
### Continuous mode
270
269
271
-
Call `start()` to run the render loop continuously at the target FPS:
270
+
Call `start()` to run render loop continuously at target FPS:
272
271
273
272
```typescript
274
273
renderer.start() // Start continuous rendering
275
274
renderer.stop() // Stop the render loop
276
275
```
277
276
278
-
You can change the render loop cadence at runtime. `targetFps` sets the steady-state continuous render rate. `maxFps` caps how often `requestRender()` can produce an immediate extra frame:
277
+
change render loop cadence at runtime. `targetFps` sets steady-state continuous render rate. `maxFps` caps how often `requestRender()` can produce immediate extra frame:
279
278
280
279
```typescript
281
280
renderer.targetFps = 60
···
294
293
renderer.dropLive()
295
294
```
296
295
297
-
Multiple components can request animations at the same time. The renderer stays live until all requests drop.
296
+
Multiple components can request animations at same time. renderer stays live until all requests drop.
298
297
299
298
### Pause and suspend
300
299
···
305
304
renderer.resume() // Resume from suspended state
306
305
```
307
306
308
-
By default, suspending or destroying clears the region OpenTUI owns on the main screen. If you want to keep that
307
+
By default, suspending or destroying clears region OpenTUI owns on main screen. If want to keep that
309
308
content visible after shutdown, set `clearOnShutdown: false`:
310
309
311
310
```typescript
···
380
379
381
380
## Theme mode
382
381
383
-
OpenTUI detects the terminal's preferred color scheme (dark or light) through two mechanisms:
382
+
OpenTUI detects terminal's preferred color scheme (dark or light) through two mechanisms:
384
383
385
384
1. **DEC mode 2031** (`CSI ? 997 ; ... n`): terminals that support it report changes live.
386
-
2. **OSC 10/11 fallback**: if the terminal does not support DEC 2031, OpenTUI inspects the terminal's foreground and background colors, then derives the mode from the background brightness.
385
+
2. **OSC 10/11 fallback**: if terminal does not support DEC 2031, OpenTUI inspects terminal's foreground and background colors, then derives mode from background brightness.
387
386
388
-
Read the current mode via `renderer.themeMode` (`"dark"`, `"light"`, or `null` before detection completes) and subscribe to the `theme_mode` event for later changes.
387
+
Read current mode via `renderer.themeMode` (`"dark"`, `"light"`, or `null` before detection completes) and subscribe to `theme_mode` event for later changes.
389
388
390
389
```typescript
391
390
import { type ThemeMode } from "@opentui/core"
···
397
396
})
398
397
```
399
398
400
-
DEC 2031 always wins over the OSC fallback, so a terminal that starts without DEC support but gains it later still reports the correct mode.
399
+
DEC 2031 always wins over OSC fallback, so terminal that starts without DEC support but gains it later still reports correct mode.
401
400
402
401
### `waitForThemeMode(timeoutMs?)`
403
402
404
-
Use `waitForThemeMode` if you need to block briefly for theme detection at startup — for example, to pick a light or dark color palette before the first paint. It resolves with the detected mode, or `null` if the timeout elapses before either source reports.
403
+
Use `waitForThemeMode` if need to block briefly for theme detection at startup — for example, to pick light or dark color palette before first paint. It resolves with detected mode, or `null` if timeout elapses before either source reports.
405
404
406
405
```typescript
407
406
const mode = await renderer.waitForThemeMode(1000) // defaults to 1000 ms
408
407
```
409
408
410
-
Pass `0` to read the current mode synchronously without waiting.
409
+
Pass `0` to read current mode synchronously without waiting.
411
410
412
411
## Terminal integration
413
412
414
-
These methods drive the terminal emulator directly, outside of the render buffer:
413
+
These methods drive terminal emulator directly, outside of render buffer:
415
414
416
415
### Terminal title and background
417
416
···
426
425
renderer.resetTerminalBgColor()
427
426
```
428
427
429
-
`destroy()` and `suspend()` call `resetTerminalBgColor()` for you. Call it yourself only for cases the renderer does not own — for example, before pausing with SIGTSTP.
428
+
`destroy()` and `suspend()` call `resetTerminalBgColor()` for you. Call it yourself only for cases renderer does not own — for example, before pausing with SIGTSTP.
430
429
431
430
### OSC 52 clipboard
432
431
433
-
OpenTUI can set and clear the terminal's clipboard via OSC 52. This works across SSH sessions and remote editors. Terminals that opt out silently ignore these calls.
432
+
OpenTUI can set and clear terminal's clipboard via OSC 52. This works across SSH sessions and remote editors. Terminals that opt out silently ignore these calls.
434
433
435
434
```typescript
436
435
if (renderer.isOsc52Supported()) {
···
443
442
renderer.copyToClipboardOSC52("both", "clipboard-primary")
444
443
```
445
444
446
-
`ClipboardTarget` values are `"clipboard"`, `"primary"`, or `"clipboard-primary"`. Both methods return `false` if the renderer cannot write to stdout — for example, after you destroy it.
445
+
`ClipboardTarget` values are `"clipboard"`, `"primary"`, or `"clipboard-primary"`. Both methods return `false` if renderer cannot write to stdout — for example, after you destroy it.
447
446
448
447
### Raw OSC sequences
449
448
450
-
Subscribe to raw OSC sequences the terminal emits — palette queries, cursor position reports, custom escape codes. Use this when you integrate OpenTUI with a terminal feature that does not have a dedicated API yet.
449
+
Subscribe to raw OSC sequences terminal emits — palette queries, cursor position reports, custom escape codes. Use this when you integrate OpenTUI with terminal feature that does not have dedicated API yet.
451
450
452
451
```typescript
453
452
const unsubscribe = renderer.subscribeOsc((sequence) => {
···
460
459
461
460
## Cursor control
462
461
463
-
Use these methods to control the cursor position and style:
462
+
Use these methods to control cursor position and style:
464
463
465
464
```typescript
466
465
// Position and visibility
···
508
507
})
509
508
```
510
509
511
-
By default, `addInputHandler()` appends handlers to the chain and runs them after built-in handlers. Use `prependInputHandler()` to add a handler at the start of the chain and run it before built-in handlers.
510
+
By default, `addInputHandler()` appends handlers to chain and runs them after built-in handlers. Use `prependInputHandler()` to add handler at start of chain and run it before built-in handlers.
512
511
513
512
## Debug overlay
514
513
515
-
Use the debug overlay to show FPS, memory usage, and other stats:
514
+
Use debug overlay to show FPS, memory usage, and other stats:
516
515
517
516
```typescript
518
517
renderer.toggleDebugOverlay()
···
528
527
529
528
## Cleanup
530
529
531
-
Always destroy the renderer when you finish so you restore the terminal state:
530
+
Always destroy renderer when you finish so you restore terminal state:
532
531
533
532
```typescript
534
533
renderer.destroy()
535
534
```
536
535
537
-
Destroying the renderer restores the terminal to its original state, disables mouse tracking, and cleans up resources.
536
+
Destroying renderer restores terminal to its original state, disables mouse tracking, and cleans up resources.
538
537
539
538
**Important:** OpenTUI does not automatically clean up on `process.exit` or unhandled errors. This design gives you control. See [Lifecycle](/docs/core-concepts/lifecycle/) for signal handling options and best practices.
540
539
541
540
## Environment variables
542
541
543
-
See the [environment variable reference](/docs/reference/env-vars) for the full list.
542
+
See [environment variable reference](/docs/reference/env-vars) for full list.
544
543
545
-
The renderer-specific ones you will most likely care about are:
544
+
renderer-specific ones you will most likely care about are:
546
545
547
546
- `OTUI_USE_CONSOLE` controls global `console.*` capture.
548
-
- `SHOW_CONSOLE` opens the built-in console overlay at startup.
549
-
- `OTUI_NO_NATIVE_RENDER` skips the Zig/native frame renderer. In `"split-footer"` mode, the current stdout flush path can still write ANSI.
550
-
- `OTUI_DUMP_CAPTURES` dumps captured stdout and console caches from the renderer exit handler.
547
+
- `SHOW_CONSOLE` opens built-in console overlay at startup.
548
+
- `OTUI_NO_NATIVE_RENDER` skips Zig/native frame renderer. In `"split-footer"` mode, current stdout flush path can still write ANSI.
549
+
- `OTUI_DUMP_CAPTURES` dumps captured stdout and console caches from renderer exit handler.
+8
-8
skills/opentui/docs/getting-started.mdx
+8
-8
skills/opentui/docs/getting-started.mdx
···
4
4
order: 1
5
5
navTitle: Introduction
6
6
skill:
7
-
entry: true
8
-
intents: [getting-started, installation, quickstart, intro]
7
+
entry: true
8
+
intents: [getting-started, installation, quickstart, intro]
9
9
---
10
10
11
11
# Getting started
12
12
13
-
OpenTUI is a native terminal UI core written in Zig with TypeScript bindings. The native core exposes a C ABI and can be used from any language. OpenTUI powers OpenCode in production today and will also power terminal.shop. It is an extensible core with a focus on correctness, stability, and high performance. It provides a component-based architecture with flexible layout capabilities, allowing you to create complex terminal applications.
13
+
OpenTUI is native terminal UI core written in Zig with TypeScript bindings. native core exposes C ABI and can be used from any language. OpenTUI powers OpenCode in production today and will also power terminal.shop. it's extensible core with focus on correctness, stability, and high performance. It provides component-based architecture with flexible layout capabilities, allowing you to create complex terminal applications.
14
14
15
15
## Installation
16
16
···
47
47
bun index.ts
48
48
```
49
49
50
-
You should see green text. Press `Ctrl+C` to exit.
50
+
see green text. Press `Ctrl+C` to exit.
51
51
52
52
## Composing components
53
53
54
-
Components nest naturally. Here's a bordered panel with content:
54
+
Components nest naturally. Here's bordered panel with content:
55
55
56
56
```typescript
57
57
import { createCliRenderer, Box, Text } from "@opentui/core"
···
69
69
)
70
70
```
71
71
72
-
`Box` and `Text` are factory functions. The first argument is props; additional arguments are children.
72
+
`Box` and `Text` are factory functions. first argument is props; additional arguments are children.
73
73
74
74
## What's next
75
75
76
76
### Core concepts
77
77
78
-
- [Renderer](/docs/core-concepts/renderer) - The rendering engine
78
+
- [Renderer](/docs/core-concepts/renderer) - rendering engine
79
79
- [Layout](/docs/core-concepts/layout) - Flexbox positioning
80
-
- [Constructs](/docs/core-concepts/constructs) - The declarative component API
80
+
- [Constructs](/docs/core-concepts/constructs) - declarative component API
81
81
82
82
### Components
83
83
+13
-13
skills/opentui/docs/keymap/addons.mdx
+13
-13
skills/opentui/docs/keymap/addons.mdx
···
7
7
8
8
# Built-in keymap addons
9
9
10
-
`@opentui/keymap` keeps the engine bare. The built-in addon packages install parser stages, field compilers, diagnostics, disambiguation and host-specific helpers on top of the public registration APIs.
10
+
`@opentui/keymap` keeps engine bare. built-in addon packages install parser stages, field compilers, diagnostics, disambiguation and host-specific helpers on top of public registration APIs.
11
11
12
-
If you want to build your own addon, see [Custom Addons](/docs/keymap/custom-addons).
12
+
If want to build your own addon, see [Custom Addons](/docs/keymap/custom-addons).
13
13
14
-
Every addon returns a disposer.
14
+
Every addon returns disposer.
15
15
16
16
```ts
17
17
import * as addons from "@opentui/keymap/addons"
···
30
30
| `registerDefaultEventMatchResolver()` | Appends `defaultEventMatchResolver` |
31
31
| `registerDefaultKeys()` | Installs both default stages together |
32
32
33
-
The shared default parser accepts single-stroke named keys, modifier chords, literal punctuation, `" "` for space, `"+"` as a literal plus key and `<token>` segments. It parses concatenated multi-stroke sequences such as `dd` or `<leader>s`.
33
+
shared default parser accepts single-stroke named keys, modifier chords, literal punctuation, `" "` for space, `"+"` as literal plus key and `<token>` segments. It parses concatenated multi-stroke sequences such as `dd` or `<leader>s`.
34
34
35
35
Recognized modifier prefixes (case-insensitive, joined with `+`):
36
36
···
51
51
| `registerMetadataFields()` | Binding `desc` / `group` and command `desc` / `title` / `category` attrs |
52
52
| `registerAliasesField()` | Layer-local `aliases` field for remapping single-key binding names |
53
53
54
-
`registerBindingOverrides()` expects `bindingOverrides` to already be a `BindingInput[]` array. It rewrites that layer's binding array once at registration time. Matching string commands are replaced by the override binding and unmatched bindings stay in place.
54
+
`registerBindingOverrides()` expects `bindingOverrides` to already be `BindingInput[]` array. It rewrites that layer's binding array once at registration time. Matching string commands are replaced by override binding and unmatched bindings stay in place.
55
55
56
56
`registerEnabledFields()` accepts `boolean`, `() => boolean`, or `ReactiveMatcher` values. It applies to layers and commands, not bindings.
57
57
58
-
`registerAliasesField()` adds bindings instead of replacing the originals and aliases stay local to the layer that declared them.
58
+
`registerAliasesField()` adds bindings instead of replacing originals and aliases stay local to layer that declared them.
59
59
60
60
### Syntax and sequence addons
61
61
···
90
90
91
91
## Ex commands
92
92
93
-
`registerExCommands()` installs a command layer plus a command resolver for `:name ...args` strings.
93
+
`registerExCommands()` installs command layer plus command resolver for `:name ...args` strings.
94
94
95
95
```ts
96
96
import { registerExCommands } from "@opentui/keymap/addons"
···
122
122
- Registered ex commands default `namespace` to `excommands`.
123
123
- Aliases produce additional registered commands, for example `:write` and `:w`.
124
124
- Extra fields are preserved on `getCommands()` / `getCommandEntries()` results and compiled through command-field addons.
125
-
- `runCommand(":write file.txt")` and `dispatchCommand(":write file.txt")` both go through the installed resolver.
125
+
- `runCommand(":write file.txt")` and `dispatchCommand(":write file.txt")` both go through installed resolver.
126
126
127
127
## OpenTUI addons
128
128
129
-
`@opentui/keymap/addons/opentui` re-exports every universal addon and adds the OpenTUI-specific helpers below.
129
+
`@opentui/keymap/addons/opentui` re-exports every universal addon and adds OpenTUI-specific helpers below.
130
130
131
131
### `registerBaseLayoutFallback()`
132
132
133
-
Adds an event match resolver that falls back to `KeyEvent.baseCode` so bindings can ignore active keyboard layout changes when Kitty base-layout reporting is available. Direct stroke matches still win ahead of the fallback.
133
+
Adds event match resolver that falls back to `KeyEvent.baseCode` so bindings can ignore active keyboard layout changes when Kitty base-layout reporting is available. Direct stroke matches still win ahead of fallback.
134
134
135
135
### Edit buffer helpers
136
136
···
141
141
| `registerTextareaMappingSuspension()` | Suspends focused `TextareaRenderable` mapped shortcuts while keeping plain typing intact |
142
142
| `registerManagedTextareaLayer()` | High-level textarea integration: commands, suspension, default bindings and overrides |
143
143
144
-
`registerManagedTextareaLayer()` accepts a global `Layer` shape plus optional `bindings`, but it intentionally excludes `target` and `targetMode`. The helper is global and follows `renderer.currentFocusedEditor`.
144
+
`registerManagedTextareaLayer()` accepts global `Layer` shape plus optional `bindings`, but it intentionally excludes `target` and `targetMode`. helper is global and follows `renderer.currentFocusedEditor`.
145
145
146
146
`EditBufferCommandOptions`:
147
147
···
193
193
| `select-all` | `input.select.all` | Select all |
194
194
| `submit` | `input.submit` | Submit |
195
195
196
-
The generated textarea bindings come from the shared `defaultTextareaKeyBindings` in `@opentui/core`. `createTextareaBindings()` prepends overrides before those defaults so custom bindings win by order.
196
+
generated textarea bindings come from shared `defaultTextareaKeyBindings` in `@opentui/core`. `createTextareaBindings()` prepends overrides before those defaults so custom bindings win by order.
197
197
198
-
See [Custom Addons](/docs/keymap/custom-addons) for the public addon-authoring APIs, lifecycle rules, callback contexts and extension-point quirks.
198
+
See [Custom Addons](/docs/keymap/custom-addons) for public addon-authoring APIs, lifecycle rules, callback contexts and extension-point quirks.
+30
-30
skills/opentui/docs/keymap/core.mdx
+30
-30
skills/opentui/docs/keymap/core.mdx
···
8
8
9
9
This page covers `@opentui/keymap` without any host-specific adapter.
10
10
11
-
Use the bare engine when you want a custom host or when you want to build addons on top of the shared registration surface. If you want a ready-made host or need the host contract, start with [Hosts](/docs/keymap/hosts).
11
+
Use bare engine when you want custom host or when want to build addons on top of shared registration surface. If you want ready-made host or need host contract, start with [Hosts](/docs/keymap/hosts).
12
12
13
13
## Construct a keymap
14
14
···
18
18
const keymap = new Keymap(host as KeymapHost<object>)
19
19
```
20
20
21
-
Bare keymaps do not parse string bindings until you install binding parsers and event match resolvers. In practice that usually means `registerDefaultKeys()` or one of the default host helpers.
21
+
Bare keymaps do not parse string bindings until you install binding parsers and event match resolvers. In practice that usually means `registerDefaultKeys()` or one of default host helpers.
22
22
23
23
## `KeymapHost`
24
24
25
-
`KeymapHost` is the contract that built-in hosts and custom adapters implement. See [Hosts](/docs/keymap/hosts) for the built-in OpenTUI and HTML adapters.
25
+
`KeymapHost` is contract that built-in hosts and custom adapters implement. See [Hosts](/docs/keymap/hosts) for built-in OpenTUI and HTML adapters.
26
26
27
27
| Member | Required | Description |
28
28
| ----------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
···
81
81
| extra fields | Feed layer-field compilers and binding compilation. Layer fields do not surface public attrs |
82
82
83
83
- Targetless layers are always active.
84
-
- Active layers all use the same precedence rules: higher `priority` wins, then newer layers win.
85
-
- Returning `false` from a command rejects that candidate so lower-precedence handlers can continue.
86
-
- `fallthrough` and `preventDefault` are independent. `fallthrough` continues inside the keymap; `preventDefault` controls whether the event escapes to the host.
84
+
- Active layers all use same precedence rules: higher `priority` wins, then newer layers win.
85
+
- Returning `false` from command rejects that candidate so lower-precedence handlers can continue.
86
+
- `fallthrough` and `preventDefault` are independent. `fallthrough` continues inside keymap; `preventDefault` controls whether event escapes to host.
87
87
88
88
## Bindings
89
89
···
94
94
| Object stroke | `{ name: "return", ctrl: true }` | Skips string parsing and normalizes directly |
95
95
| Release binding | `{ key: "a", event: "release", ...}` | Release bindings support a single stroke only |
96
96
97
-
The core engine only accepts full `BindingInput[]` arrays. If you want command-to-key config sugar, use `commandBindings(map)` from `@opentui/keymap/extras` to build the array before calling `registerLayer()`.
97
+
core engine only accepts full `BindingInput[]` arrays. If you want command-to-key config sugar, use `commandBindings(map)` from `@opentui/keymap/extras` to build array before calling `registerLayer()`.
98
98
99
99
`BindingInput` reserves `key`, `cmd`, `event`, `preventDefault` and `fallthrough`. All other fields are available to binding-field compilers.
100
100
···
108
108
109
109
Release bindings dispatch on key release, but they do not appear in `getActiveKeys()` because active-key discovery is based on press/pending-sequence state.
110
110
111
-
The shared default parser understands single-stroke named keys, modifier chords, literal punctuation, `" "` for space, `"+"` as a literal plus key and `<token>` segments. Spaced Emacs-style sequences such as `ctrl+x ctrl+s` are not part of the default parser.
111
+
shared default parser understands single-stroke named keys, modifier chords, literal punctuation, `" "` for space, `"+"` as literal plus key and `<token>` segments. Spaced Emacs-style sequences such as `ctrl+x ctrl+s` are not part of default parser.
112
112
113
113
## State and discovery
114
114
···
213
213
formatCommandBindings(keymap.getCommandBindings({ visibility: "registered", commands: ["save-file"] }).get("save-file"))
214
214
```
215
215
216
-
`resolveBindingSections()` is an opinionated config-to-keymap transformation for app-level config split by real registration site. It is one practical shape; copy and adjust it if your app needs different rules. Values can be `false`, `"none"`, a key, a full binding object, or arrays of keys/binding objects. `false`, `"none"`, and empty arrays emit no bindings. The command name comes from the record key.
216
+
`resolveBindingSections()` is opinionated config-to-keymap transformation for app-level config split by real registration site. it's one practical shape; copy and adjust it if your app needs different rules. Values can be `false`, `"none"`, key, full binding object, or arrays of keys/binding objects. `false`, `"none"`, and empty arrays emit no bindings. command name comes from record key.
217
217
218
218
```ts
219
219
import { resolveBindingSections } from "@opentui/keymap/extras"
···
234
234
resolved.get("app", "app.exit")
235
235
```
236
236
237
-
Tokens such as `<leader>` are still registered through the normal keymap token APIs.
237
+
Tokens such as `<leader>` are still registered through normal keymap token APIs.
238
238
239
-
`dispatchCommand()` respects current activation and can return `inactive` or `disabled` when the command exists but is not currently dispatchable. `runCommand()` walks the registered chain directly, so it can execute command-only layers programmatically even when they do not have an active binding.
239
+
`dispatchCommand()` respects current activation and can return `inactive` or `disabled` when command exists but is not currently dispatchable. `runCommand()` walks registered chain directly, so it can execute command-only layers programmatically even when they do not have active binding.
240
240
241
241
`RunCommandResult` is `{ ok: true, command? }` on success or `{ ok: false, reason, command? }` on failure. Reject reasons:
242
242
···
249
249
| `rejected` | Every candidate's handler returned synchronous `false` |
250
250
| `error` | A resolver, runtime matcher, or handler threw synchronously |
251
251
252
-
`command` is included on rejected results when `includeCommand: true` is set and the keymap could resolve a record for the name.
252
+
`command` is included on rejected results when `includeCommand: true` is set and keymap could resolve record for name.
253
253
254
-
Command handlers may be sync or async. Only a synchronous `false` rejects the candidate and lets lower-precedence handlers continue. A returned promise is treated as handled immediately; async rejection is reported through the `error` diagnostic event.
254
+
Command handlers may be sync or async. Only synchronous `false` rejects candidate and lets lower-precedence handlers continue. returned promise is treated as handled immediately; async rejection is reported through `error` diagnostic event.
255
255
256
256
`RunCommandOptions`:
257
257
···
281
281
| `searchIn` | Additional fields/attrs to search |
282
282
| `filter` | Object or predicate filter against raw fields and compiled attrs |
283
283
284
-
- `reachable` dedupes by command name using the current dispatch winner.
284
+
- `reachable` dedupes by command name using current dispatch winner.
285
285
- `active` keeps every active candidate in precedence order, including same-name duplicates.
286
286
- `registered` ignores focus and returns all registered commands.
287
287
288
-
Use `getCommandEntries()` for command palettes, searchable help screens and other discovery surfaces that need command records plus their bindings. It runs the full `CommandQuery`, materializes command metadata and attaches matching bindings, so it is the heavier query.
288
+
Use `getCommandEntries()` for command palettes, searchable help screens and other discovery surfaces that need command records plus their bindings. It runs full `CommandQuery`, materializes command metadata and attaches matching bindings, so it's heavier query.
289
289
290
-
Use `getCommandBindings()` when a UI already knows the commands it wants to label and only needs their bindings:
290
+
Use `getCommandBindings()` when UI already knows commands it wants to label and only needs their bindings:
291
291
292
292
```ts
293
293
const bindingsByCommand = keymap.getCommandBindings({
···
298
298
const saveBindings = bindingsByCommand.get("file.save") ?? []
299
299
```
300
300
301
-
The returned map preserves the requested command order and includes every requested command with `[]` when no matching bindings exist. Formatting remains app-owned; each returned `ActiveBinding` includes its parsed `sequence`.
301
+
returned map preserves requested command order and includes every requested command with `[]` when no matching bindings exist. Formatting remains app-owned; each returned `ActiveBinding` includes its parsed `sequence`.
302
302
303
303
`CommandBindingsQuery` fields:
304
304
···
319
319
| `warning` | `WarningEvent` | Validation or analyzer warning |
320
320
| `error` | `ErrorEvent` | Registration, query, resolver, or listener error |
321
321
322
-
Diagnostic events are not batched through `state`; they are emitted when the warning or error is reported.
322
+
Diagnostic events are not batched through `state`; they are emitted when warning or error is reported.
323
323
324
324
`WarningEvent` and `ErrorEvent` payloads:
325
325
···
330
330
331
331
Diagnostic-event quirks:
332
332
333
-
- If no `warning` listener is registered, the keymap falls back to `console.warn(...)` for warnings.
334
-
- If no `error` listener is registered, the keymap falls back to `console.error(...)` for errors.
335
-
- Console fallback is per event type. Registering a `warning` listener suppresses warning console output but does not affect `error`, and vice versa.
336
-
- Console fallback prefixes the message with `[code]`. If the underlying cause is an `Error`, it is passed as the second console argument.
333
+
- If no `warning` listener is registered, keymap falls back to `console.warn(...)` for warnings.
334
+
- If no `error` listener is registered, keymap falls back to `console.error(...)` for errors.
335
+
- Console fallback is per event type. Registering `warning` listener suppresses warning console output but does not affect `error`, and vice versa.
336
+
- Console fallback prefixes message with `[code]`. If underlying cause is `Error`, it's passed as second console argument.
337
337
- Throwing `warning` or `error` listeners do not stop remaining diagnostic listeners from running, and they do not recursively emit another keymap error event.
338
338
- `warning` commonly covers analyzer and validation warnings such as unknown fields or unknown tokens.
339
339
- `error` covers more than registration failures: it also reports resolver failures, command-query failures, runtime matcher failures, and thrown `state` / `pendingSequence` listeners.
···
369
369
| `prepend/appendDisambiguationResolver(fn)` | Choose exact-vs-prefix behavior for ambiguous sequences |
370
370
| `acquireResource(symbol, setup)` | Share ref-counted setup/teardown across multiple addon registrations |
371
371
372
-
Every registration method above returns a disposer. The matching `clear*()` methods remove all registrations for that stage.
372
+
Every registration method above returns disposer. matching `clear*()` methods remove all registrations for that stage.
373
373
374
374
## Disambiguation
375
375
376
-
Ambiguity happens when the same sequence is both an exact command and a prefix of a longer binding, for example `g` and `gg`.
376
+
Ambiguity happens when same sequence is both exact command and prefix of longer binding, for example `g` and `gg`.
377
377
378
-
Same-layer exact/prefix ambiguity is only allowed when at least one disambiguation resolver is registered. Without one, registering both `g` and `gg` in the same layer emits a compile error and keeps the valid earlier bindings.
378
+
Same-layer exact/prefix ambiguity is only allowed when at least one disambiguation resolver is registered. Without one, registering both `g` and `gg` in same layer emits compile error and keeps valid earlier bindings.
379
379
380
380
```ts
381
381
keymap.appendDisambiguationResolver((ctx) => {
···
402
402
| `clear()` | Clear the pending sequence and consume the key |
403
403
| `defer(handler)` | Start cancellable async disambiguation work |
404
404
405
-
Disambiguation resolvers must return synchronously. For async behavior, use `ctx.defer(...)`. If no resolver decides, the engine falls back to prefix handling and emits a warning.
405
+
Disambiguation resolvers must return synchronously. For async behavior, use `ctx.defer(...)`. If no resolver decides, engine falls back to prefix handling and emits warning.
406
406
407
-
`defer(handler)` invokes `handler` with a `KeyDeferredDisambiguationContext`:
407
+
`defer(handler)` invokes `handler` with `KeyDeferredDisambiguationContext`:
408
408
409
409
| Member | Description |
410
410
| -------------------- | --------------------------------------------------------------------------------------------------------- |
···
416
416
| `continueSequence()` | Decision: keep the prefix pending |
417
417
| `clear()` | Decision: clear the pending sequence |
418
418
419
-
The handler may return a decision, a `Promise<decision>`, or nothing (no-op). Returning nothing after the signal aborted is the canonical cancel path.
419
+
handler may return decision, `Promise<decision>`, or nothing (no-op). Returning nothing after signal aborted is canonical cancel path.
420
420
421
421
## Constraints
422
422
423
423
- Runtime/data re-entry is supported during dispatch. Command handlers, intercepts and pending-sequence listeners can read and write runtime data.
424
-
- Structural re-entry is not supported during dispatch. Do not register or unregister layers, parsers, resolvers, tokens, or similar environment-shaping state while a dispatch is in flight.
425
-
- After the host is destroyed, host-backed reads such as `getActiveKeys()` are unavailable. Metadata reads such as `getCommands()` and runtime data access remain usable.
424
+
- Structural re-entry is not supported during dispatch. Do not register or unregister layers, parsers, resolvers, tokens, or similar environment-shaping state while dispatch is in flight.
425
+
- After host is destroyed, host-backed reads such as `getActiveKeys()` are unavailable. Metadata reads such as `getCommands()` and runtime data access remain usable.
426
426
427
427
Example host surface: `packages/keymap/src/tests/keymap.host.test.ts`
+38
-38
skills/opentui/docs/keymap/custom-addons.mdx
+38
-38
skills/opentui/docs/keymap/custom-addons.mdx
···
7
7
8
8
# Custom keymap addons
9
9
10
-
An addon is usually a function that accepts a `Keymap`, registers one or more behaviors, and returns a disposer.
10
+
addon is usually function that accepts `Keymap`, registers one or more behaviors, and returns disposer.
11
11
12
-
The important constraint is that custom addons should stay on the public surface. The built-in addons are implemented that way too.
12
+
important constraint is that custom addons should stay on public surface. built-in addons are implemented that way too.
13
13
14
-
If you want the shipped addon inventory instead, see [Built-in Addons](/docs/keymap/addons).
14
+
If you want shipped addon inventory instead, see [Built-in Addons](/docs/keymap/addons).
15
15
16
16
## Addon shape
17
17
···
43
43
44
44
Guidelines:
45
45
46
-
- Return one disposer that tears down everything the addon registered.
47
-
- Clean up in reverse order when the registrations depend on one another.
48
-
- Prefer composing the public registration methods over reaching into internal services.
46
+
- Return one disposer that tears down everything addon registered.
47
+
- Clean up in reverse order when registrations depend on one another.
48
+
- Prefer composing public registration methods over reaching into internal services.
49
49
50
50
## Public registration APIs
51
51
···
85
85
| `acquireResource(symbol, setup)` | Share ref-counted setup and teardown across multiple registrations |
86
86
| `on("state" \| "pendingSequence" \| "warning" \| "error", ...)` | Subscribe to derived-state and diagnostic events |
87
87
88
-
Every registration API above returns a disposer.
88
+
Every registration API above returns disposer.
89
89
90
90
## Field compilers
91
91
···
100
100
Important behavior:
101
101
102
102
- `require(name, value)` ties activation to `keymap` runtime data.
103
-
- `activeWhen(...)` accepts either a raw callback or a `ReactiveMatcher`.
103
+
- `activeWhen(...)` accepts either raw callback or `ReactiveMatcher`.
104
104
- `attr(name, value)` exposes compiled metadata through query surfaces.
105
-
- Layer fields do not have `attr(...)` because there is no layer-level public attrs surface.
105
+
- Layer fields do not have `attr(...)` because there's no layer-level public attrs surface.
106
106
107
-
`ReactiveMatcher` is the cache-friendly form:
107
+
`ReactiveMatcher` is cache-friendly form:
108
108
109
109
```ts
110
110
interface ReactiveMatcher {
···
117
117
118
118
## Binding pipeline callbacks
119
119
120
-
String bindings go through an ordered pipeline.
120
+
String bindings go through ordered pipeline.
121
121
122
-
1. Expanders rewrite the input string.
122
+
1. Expanders rewrite input string.
123
123
2. Parsers turn strings into `KeySequencePart[]`.
124
124
3. Transformers rewrite parsed bindings or add more.
125
125
126
-
Layer-binding transformers run earlier than that pipeline and only once, when the layer is registered. Use them when an addon needs to replace or filter the whole `BindingInput[]` set before compilation.
126
+
Layer-binding transformers run earlier than that pipeline and only once, when layer is registered. Use them when addon needs to replace or filter whole `BindingInput[]` set before compilation.
127
127
128
128
Object-form keys such as `{ name: "return", ctrl: true }` skip string parsing and normalize directly.
129
129
···
168
168
Ordering rules:
169
169
170
170
- `prepend*` registrations run before `append*` registrations.
171
-
- `clearBindingExpanders()`, `clearBindingParsers()` and `clearBindingTransformers()` remove the entire stage for that keymap.
171
+
- `clearBindingExpanders()`, `clearBindingParsers()` and `clearBindingTransformers()` remove entire stage for that keymap.
172
172
173
-
Use the `clear*()` methods only when your addon owns that whole stage. They are global to the keymap, not scoped to your addon.
173
+
Use `clear*()` methods only when your addon owns that whole stage. They are global to keymap, not scoped to your addon.
174
174
175
175
## Command, event and disambiguation callbacks
176
176
···
196
196
| `record` | Custom `CommandRecord` metadata |
197
197
| `rejectedResult` | Override the default rejected result |
198
198
199
-
Resolver results used for static binding commands and command-view projections may be cached for the lifetime of that active or registered view.
200
-
Programmatic `runCommand()` and `dispatchCommand()` resolve the supplied command string for each call.
201
-
Put per-execution behavior in the returned `run(ctx)` handler.
199
+
Resolver results used for static binding commands and command-view projections may be cached for lifetime of that active or registered view.
200
+
Programmatic `runCommand()` and `dispatchCommand()` resolve supplied command string for each call.
201
+
Put per-execution behavior in returned `run(ctx)` handler.
202
202
203
203
### `EventMatchResolver`
204
204
···
206
206
(event, ctx) => readonly KeyMatch[] | undefined
207
207
```
208
208
209
-
`EventMatchResolverContext` exposes `resolveKey(key)`, which lets a resolver map a host event to the same internal match keys the parser uses.
209
+
`EventMatchResolverContext` exposes `resolveKey(key)`, which lets resolver map host event to same internal match keys parser uses.
210
210
211
211
### `KeyDisambiguationResolver`
212
212
213
-
Use this when the same sequence is both an exact command and a prefix, such as `g` and `gg`.
213
+
Use this when same sequence is both exact command and prefix, such as `g` and `gg`.
214
214
215
-
Register a disambiguation resolver before registering same-layer exact/prefix bindings. Without a resolver, the compiler rejects the ambiguous binding and keeps the valid earlier bindings.
215
+
Register disambiguation resolver before registering same-layer exact/prefix bindings. Without resolver, compiler rejects ambiguous binding and keeps valid earlier bindings.
216
216
217
217
`KeyDisambiguationContext` exposes:
218
218
···
229
229
| `clear()` | Clear the pending sequence |
230
230
| `defer(handler)` | Start cancellable async disambiguation work |
231
231
232
-
Disambiguation resolvers themselves must return synchronously. If you need async behavior, use `ctx.defer(...)`. The handler receives a `KeyDeferredDisambiguationContext`:
232
+
Disambiguation resolvers themselves must return synchronously. If you need async behavior, use `ctx.defer(...)`. handler receives `KeyDeferredDisambiguationContext`:
233
233
234
234
| Member | Purpose |
235
235
| -------------------- | --------------------------------------------------------------------------------------------------------- |
···
241
241
| `continueSequence()` | Decision: keep the prefix pending |
242
242
| `clear()` | Decision: clear the pending sequence |
243
243
244
-
The handler may return a decision, a `Promise<decision>`, or nothing. Return nothing after `signal` aborts to drop the deferred work without dispatching.
244
+
handler may return decision, `Promise<decision>`, or nothing. Return nothing after `signal` aborts to drop deferred work without dispatching.
245
245
246
-
Command handlers are different: they may return a promise, but only a synchronous `false` rejects the current candidate and lets lower-precedence handlers continue.
246
+
Command handlers are different: they may return promise, but only synchronous `false` rejects current candidate and lets lower-precedence handlers continue.
247
247
248
248
### `LayerAnalyzer`
249
249
250
-
Analyzers run while a layer compiles and receive a projected view of the compiled bindings.
250
+
Analyzers run while layer compiles and receive projected view of compiled bindings.
251
251
252
252
`LayerAnalysisContext` exposes:
253
253
···
260
260
| `checkCommandResolution(command)` | Probe whether a string command resolves |
261
261
| `warn(...)` / `warnOnce(...)` / `error(...)` | Emit diagnostics |
262
262
263
-
`clearLayerAnalyzers()` removes all registered analyzers for the keymap.
263
+
`clearLayerAnalyzers()` removes all registered analyzers for keymap.
264
264
265
265
## Hooks, intercepts and runtime helpers
266
266
···
299
299
300
300
## Shared resources with `acquireResource()`
301
301
302
-
`acquireResource(symbol, setup)` is the public way to share setup and teardown across multiple addon registrations on the same keymap.
302
+
`acquireResource(symbol, setup)` is public way to share setup and teardown across multiple addon registrations on same keymap.
303
303
304
304
Behavior:
305
305
306
-
- the first acquisition for a symbol runs `setup()`
307
-
- later acquisitions for the same symbol reuse the existing resource
308
-
- the resource disposer runs only when the last holder releases it
309
-
- active resources are disposed when the host is destroyed
310
-
- a failed `setup()` is not retained as a partially registered resource
306
+
- first acquisition for symbol runs `setup()`
307
+
- later acquisitions for same symbol reuse existing resource
308
+
- resource disposer runs only when last holder releases it
309
+
- active resources are disposed when host is destroyed
310
+
- failed `setup()` is not retained as partially registered resource
311
311
312
-
This is how the OpenTUI textarea helpers safely share command and suspension infrastructure.
312
+
This is how OpenTUI textarea helpers safely share command and suspension infrastructure.
313
313
314
314
## Constraints and quirks
315
315
···
325
325
326
326
- Unknown custom layer and binding fields are ignored and emit warnings.
327
327
- Unknown tokens inside binding strings are ignored and emit warnings.
328
-
- Registering the missing token later recompiles affected layers.
328
+
- Registering missing token later recompiles affected layers.
329
329
330
330
### Re-entry
331
331
332
332
- Runtime/data-style re-entry is supported during dispatch. Commands, intercepts and pending-sequence listeners may read and write runtime data.
333
-
- Structural re-entry is not supported during dispatch. Do not register or unregister layers, parsers, resolvers, tokens or similar environment-shaping state while a dispatch is in flight.
333
+
- Structural re-entry is not supported during dispatch. Do not register or unregister layers, parsers, resolvers, tokens or similar environment-shaping state while dispatch is in flight.
334
334
335
335
### Host-dependent behavior
336
336
337
-
- `intercept("raw", ...)` only works when the host implements `onRawInput()`.
338
-
- Raw hosts must stop raw input propagation when an `onRawInput()` listener returns `true`.
339
-
- After the host is destroyed, host-backed reads such as `getActiveKeys()` are unavailable, but metadata reads such as `getCommands()` and runtime data access remain usable.
337
+
- `intercept("raw", ...)` only works when host implements `onRawInput()`.
338
+
- Raw hosts must stop raw input propagation when `onRawInput()` listener returns `true`.
339
+
- After host is destroyed, host-backed reads such as `getActiveKeys()` are unavailable, but metadata reads such as `getCommands()` and runtime data access remain usable.
340
340
341
341
## Reference implementations
342
342
+42
-42
skills/opentui/docs/keymap/hosts.mdx
+42
-42
skills/opentui/docs/keymap/hosts.mdx
···
1
1
---
2
2
title: Hosts
3
-
description: Built-in OpenTUI and HTML adapters plus the KeymapHost contract
3
+
description: Built-in OpenTUI and HTML adapters plus KeymapHost contract
4
4
order: 2
5
5
navTitle: Hosts
6
6
---
7
7
8
8
# Keymap hosts
9
9
10
-
OpenTUI Keymap is host-agnostic. A host adapts a runtime's focus model, hierarchy, key events and lifecycle into `KeymapHost<TTarget, TEvent>` so the shared engine can work against it.
10
+
OpenTUI Keymap is host-agnostic. host adapts runtime's focus model, hierarchy, key events and lifecycle into `KeymapHost<TTarget, TEvent>` so shared engine can work against it.
11
11
12
-
The package ships two built-in hosts:
12
+
package ships two built-in hosts:
13
13
14
14
- `@opentui/keymap/opentui` for terminal apps built on `CliRenderer` and `Renderable`
15
-
- `@opentui/keymap/html` for browser UIs rooted in an `HTMLElement`
15
+
- `@opentui/keymap/html` for browser UIs rooted in `HTMLElement`
16
16
17
-
If you have not read the shared model yet, start with [Keymap overview](/docs/keymap/overview).
17
+
If you have not read shared model yet, start with [Keymap overview](/docs/keymap/overview).
18
18
19
19
## What a host does
20
20
21
-
The keymap core does not know about DOM nodes, terminal renderables or any other UI tree. It only knows about host targets and host events.
21
+
keymap core does not know about DOM nodes, terminal renderables or any other UI tree. It only knows about host targets and host events.
22
22
23
-
- `target` on a local layer is a host target object.
24
-
- `focus` and `focus-within` activation come from the host's focused target and parent traversal.
25
-
- key press and key release events come from the host event stream.
26
-
- local layers are cleaned up when the host reports that their target was destroyed or removed.
27
-
- `runCommand()` and `dispatchCommand()` need the host to create a synthetic event for programmatic execution.
28
-
- raw input interception only exists when the host implements the optional raw-input hook.
23
+
- `target` on local layer is host target object.
24
+
- `focus` and `focus-within` activation come from host's focused target and parent traversal.
25
+
- key press and key release events come from host event stream.
26
+
- local layers are cleaned up when host reports that their target was destroyed or removed.
27
+
- `runCommand()` and `dispatchCommand()` need host to create synthetic event for programmatic execution.
28
+
- raw input interception only exists when host implements optional raw-input hook.
29
29
30
30
## `KeymapHost`
31
31
···
57
57
| `stopPropagation()` | Stop later listeners from seeing the event and set `propagationStopped` to `true` |
58
58
| `propagationStopped` | `true` after `stopPropagation()` was called |
59
59
60
-
If your host implements `onRawInput()`, it must call each listener before key parsing and stop when a listener returns `true`.
60
+
If your host implements `onRawInput()`, it must call each listener before key parsing and stop when listener returns `true`.
61
61
62
62
## Built-in host helpers
63
63
64
-
Both built-in host packages re-export the shared `@opentui/keymap` API and add the same three layers of helpers:
64
+
Both built-in host packages re-export shared `@opentui/keymap` API and add same three layers of helpers:
65
65
66
66
| Package | Host adapter | Bare keymap helper | Default helper |
67
67
| ------------------------- | ----------------------------------- | ------------------------------- | -------------------------------------- |
68
68
| `@opentui/keymap/opentui` | `createOpenTuiKeymapHost(renderer)` | `createOpenTuiKeymap(renderer)` | `createDefaultOpenTuiKeymap(renderer)` |
69
69
| `@opentui/keymap/html` | `createHtmlKeymapHost(root)` | `createHtmlKeymap(root)` | `createDefaultHtmlKeymap(root)` |
70
70
71
-
- The host adapter returns a `KeymapHost` implementation.
72
-
- The bare helper creates a `new Keymap(host)` with only the host installed.
73
-
- The default helper starts from the bare helper and installs the small default addon set for that host.
71
+
- host adapter returns `KeymapHost` implementation.
72
+
- bare helper creates `new Keymap(host)` with only host installed.
73
+
- default helper starts from bare helper and installs small default addon set for that host.
74
74
75
75
## OpenTUI host
76
76
77
-
`@opentui/keymap/opentui` is the host package for terminal apps built on `@opentui/core`.
77
+
`@opentui/keymap/opentui` is host package for terminal apps built on `@opentui/core`.
78
78
79
79
### What it adds
80
80
81
81
- `createOpenTuiKeymapHost(renderer)` - adapts `CliRenderer` and `Renderable` to `KeymapHost`
82
-
- `createOpenTuiKeymap(renderer)` - creates a bare `Keymap<Renderable, KeyEvent>`
83
-
- `createDefaultOpenTuiKeymap(renderer)` - creates an OpenTUI keymap with the default parser, enabled fields and metadata fields installed
82
+
- `createOpenTuiKeymap(renderer)` - creates bare `Keymap<Renderable, KeyEvent>`
83
+
- `createDefaultOpenTuiKeymap(renderer)` - creates OpenTUI keymap with default parser, enabled fields and metadata fields installed
84
84
85
85
### Basic usage
86
86
···
104
104
})
105
105
```
106
106
107
-
If you want to control the installed addons yourself, start from `createOpenTuiKeymap(renderer)` and register addons manually.
107
+
If want to control installed addons yourself, start from `createOpenTuiKeymap(renderer)` and register addons manually.
108
108
109
109
### Host behavior
110
110
···
119
119
| Raw input interception | `renderer.prependInputHandler(...)` |
120
120
| Synthetic command event | New `KeyEvent` with `name: "command"` |
121
121
122
-
`createOpenTuiKeymap(renderer)` throws if the renderer is already destroyed.
122
+
`createOpenTuiKeymap(renderer)` throws if renderer is already destroyed.
123
123
124
124
### Default helper
125
125
···
133
133
134
134
### Event notes
135
135
136
-
- Press and release events come directly from the renderer's key input stream.
137
-
- Programmatic `runCommand()` and `dispatchCommand()` calls receive the synthetic `KeyEvent` created by `createCommandEvent()`.
136
+
- Press and release events come directly from renderer's key input stream.
137
+
- Programmatic `runCommand()` and `dispatchCommand()` calls receive synthetic `KeyEvent` created by `createCommandEvent()`.
138
138
- Kitty-specific fields on `KeyEvent`, such as `baseCode`, stay available to addons like `registerBaseLayoutFallback()`.
139
139
140
140
### OpenTUI-specific addons
141
141
142
-
`@opentui/keymap/addons/opentui` adds helpers on top of the shared addon set:
142
+
`@opentui/keymap/addons/opentui` adds helpers on top of shared addon set:
143
143
144
144
- `registerBaseLayoutFallback()` - match against Kitty base-layout codepoints
145
-
- `createTextareaBindings()` - generate textarea bindings from the shared edit-buffer command set
146
-
- `registerEditBufferCommands()` - register the edit-buffer command layer against `renderer.currentFocusedEditor`
147
-
- `registerTextareaMappingSuspension()` - suspend a focused `TextareaRenderable`'s built-in mapped shortcuts
148
-
- `registerManagedTextareaLayer()` - high-level textarea integration combining the helpers above
145
+
- `createTextareaBindings()` - generate textarea bindings from shared edit-buffer command set
146
+
- `registerEditBufferCommands()` - register edit-buffer command layer against `renderer.currentFocusedEditor`
147
+
- `registerTextareaMappingSuspension()` - suspend focused `TextareaRenderable`'s built-in mapped shortcuts
148
+
- `registerManagedTextareaLayer()` - high-level textarea integration combining helpers above
149
149
150
150
Example: `packages/examples/src/keymap-demo.ts`
151
151
152
-
See [Built-in Addons](/docs/keymap/addons) for the rest of the shipped addon surface and [Custom Addons](/docs/keymap/custom-addons) for addon authoring.
152
+
See [Built-in Addons](/docs/keymap/addons) for rest of shipped addon surface and [Custom Addons](/docs/keymap/custom-addons) for addon authoring.
153
153
154
154
## HTML host
155
155
156
-
`@opentui/keymap/html` is the host package for browser UIs rooted in an `HTMLElement` subtree.
156
+
`@opentui/keymap/html` is host package for browser UIs rooted in `HTMLElement` subtree.
157
157
158
158
Live demo: [HTML keymap demo](/demos/keymap-html/)
159
159
···
161
161
162
162
- `HtmlKeymapEvent` - shared keymap event plus optional `originalEvent: KeyboardEvent`
163
163
- `normalizeHtmlKeyName(key)` - normalizes browser `event.key` values to keymap names
164
-
- `createHtmlKeymapEvent(event?)` - wraps a `KeyboardEvent` in `HtmlKeymapEvent`
165
-
- `createHtmlKeymapHost(root)` - adapts an `HTMLElement` subtree to `KeymapHost`
164
+
- `createHtmlKeymapEvent(event?)` - wraps `KeyboardEvent` in `HtmlKeymapEvent`
165
+
- `createHtmlKeymapHost(root)` - adapts `HTMLElement` subtree to `KeymapHost`
166
166
- `htmlEventMatchResolver` - HTML-specific event matcher for browser key events
167
-
- `createHtmlKeymap(root)` - creates a bare `Keymap<HTMLElement, HtmlKeymapEvent>`
168
-
- `createDefaultHtmlKeymap(root)` - creates an HTML keymap with the default parser, enabled fields, metadata fields and HTML event matching installed
167
+
- `createHtmlKeymap(root)` - creates bare `Keymap<HTMLElement, HtmlKeymapEvent>`
168
+
- `createDefaultHtmlKeymap(root)` - creates HTML keymap with default parser, enabled fields, metadata fields and HTML event matching installed
169
169
170
170
### Basic usage
171
171
···
188
188
})
189
189
```
190
190
191
-
If you want to control parser or event-matching stages yourself, start from `createHtmlKeymap(root)` and install the pieces manually.
191
+
If want to control parser or event-matching stages yourself, start from `createHtmlKeymap(root)` and install pieces manually.
192
192
193
193
### Key normalization
194
194
···
201
201
| `altKey` | `meta` | Keymap uses `meta` for Alt/Option |
202
202
| `metaKey` | `super` | Keymap uses `super` for the platform Meta key |
203
203
204
-
The HTML matcher also adds an unshifted match candidate for shifted printable punctuation, so bindings such as `":"` and `"?"` work as literal keys instead of forcing `shift+semicolon`-style spellings.
204
+
HTML matcher also adds unshifted match candidate for shifted printable punctuation, so bindings such as `":"` and `"?"` work as literal keys instead of forcing `shift+semicolon`-style spellings.
205
205
206
206
### Host behavior
207
207
···
216
216
| Raw input interception | Not provided by the HTML host |
217
217
| Synthetic command event | `createHtmlKeymapEvent()` with no DOM event |
218
218
219
-
When a target element disconnects from the rooted subtree, local layers registered against it are removed.
219
+
When target element disconnects from rooted subtree, local layers registered against it are removed.
220
220
221
221
### Default helper
222
222
···
225
225
- `registerDefaultKeys()`
226
226
- `registerEnabledFields()`
227
227
- `registerMetadataFields()`
228
-
- `htmlEventMatchResolver` via `prependEventMatchResolver(...)` so HTML-specific matching runs before the canonical matcher
228
+
- `htmlEventMatchResolver` via `prependEventMatchResolver(...)` so HTML-specific matching runs before canonical matcher
229
229
230
-
Call `prependEventMatchResolver(...)` for any custom resolver that must run before the HTML matcher.
230
+
Call `prependEventMatchResolver(...)` for any custom resolver that must run before HTML matcher.
231
231
232
232
## Custom hosts
233
233
234
-
If neither built-in host fits your runtime, implement `KeymapHost` yourself and construct the engine directly:
234
+
If neither built-in host fits your runtime, implement `KeymapHost` yourself and construct engine directly:
235
235
236
236
```ts
237
237
import { Keymap, type KeymapHost } from "@opentui/keymap"
···
239
239
const keymap = new Keymap(host as KeymapHost<object>)
240
240
```
241
241
242
-
Use [Core](/docs/keymap/core) for the bare engine APIs and extension points.
242
+
Use [Core](/docs/keymap/core) for bare engine APIs and extension points.
+49
-49
skills/opentui/docs/keymap/overview.mdx
+49
-49
skills/opentui/docs/keymap/overview.mdx
···
4
4
order: 1
5
5
navTitle: Overview
6
6
skill:
7
-
entry: true
8
-
intents: [keymap, keybindings, shortcuts, commands, leader, ex-commands]
7
+
entry: true
8
+
intents: [keymap, keybindings, shortcuts, commands, leader, ex-commands]
9
9
---
10
10
11
11
# Keymap
12
12
13
-
OpenTUI Keymap is a host-agnostic binding engine for terminals and the browser. It gives you layered shortcuts, discoverable commands, sequence handling and framework-ready state so one key system can drive the whole app.
13
+
OpenTUI Keymap is host-agnostic binding engine for terminals and browser. It gives you layered shortcuts, discoverable commands, sequence handling and framework-ready state so one key system can drive whole app.
14
14
15
15
## Installation
16
16
···
20
20
21
21
Live demo: [HTML keymap demo](/demos/keymap-html/)
22
22
23
-
A binding can target a named command, an inline handler, or a specific key event:
23
+
binding can target named command, inline handler, or specific key event:
24
24
25
25
```ts
26
26
;[
···
44
44
45
45
## Register
46
46
47
-
Shape the keymap by registering layers, tokens and addons. Each layer declares bindings that map keys or key sequences to commands, optionally scoped to a host target with a priority. Addons extend the engine with parsers, field compilers, command resolvers and more.
47
+
Shape keymap by registering layers, tokens and addons. Each layer declares bindings that map keys or key sequences to commands, optionally scoped to host target with priority. Addons extend engine with parsers, field compilers, command resolvers and more.
48
48
49
49
- Use `registerLayer()` to add bindings and commands.
50
50
- Use `registerToken()` to define named key aliases like `<leader>`.
51
51
- Use addons to install parsers, field compilers, disambiguation and other behaviour.
52
-
- Every registration call returns a disposer for cleanup.
53
-
- See [Hosts](/docs/keymap/hosts) for how targets, hierarchy and focus enter the engine.
52
+
- Every registration call returns disposer for cleanup.
53
+
- See [Hosts](/docs/keymap/hosts) for how targets, hierarchy and focus enter engine.
54
54
55
55
## Dispatch
56
56
57
-
When a key event arrives from the host, the engine walks the active layers to find matching bindings, resolves ambiguity between exact matches and sequence prefixes, and runs the winning command. Intercepts can observe or consume input before binding resolution.
57
+
When key event arrives from host, engine walks active layers to find matching bindings, resolves ambiguity between exact matches and sequence prefixes, and runs winning command. Intercepts can observe or consume input before binding resolution.
58
58
59
59
- Bindings are matched against active layers based on focus, priority and conditions.
60
-
- Multi-stroke sequences build up a pending sequence until resolved.
61
-
- Commands run in your application space. A synchronous `false` lets lower-precedence handlers continue; async commands are handled immediately and report async errors through diagnostics.
62
-
- Use `intercept("key", ...)` or `intercept("raw", ...)` to hook into the input pipeline.
60
+
- Multi-stroke sequences build up pending sequence until resolved.
61
+
- Commands run in your application space. synchronous `false` lets lower-precedence handlers continue; async commands are handled immediately and report async errors through diagnostics.
62
+
- Use `intercept("key", ...)` or `intercept("raw", ...)` to hook into input pipeline.
63
63
- See [Hosts](/docs/keymap/hosts) for how built-in hosts deliver press, release, focus and optional raw input events.
64
64
65
65
## Query
66
66
67
-
Ask the keymap what is currently available. Query results reflect the live state -- they change when focus, pending sequence, runtime data or conditions change.
67
+
Ask keymap what is currently available. Query results reflect live state -- they change when focus, pending sequence, runtime data or conditions change.
68
68
69
-
- `getActiveKeys()` returns the keys that can fire from the current focus and pending state.
69
+
- `getActiveKeys()` returns keys that can fire from current focus and pending state.
70
70
- `getCommands()`, `getCommandEntries()` and `getCommandBindings()` return command metadata and binding projections.
71
-
- `getPendingSequence()` returns the current multi-stroke prefix.
71
+
- `getPendingSequence()` returns current multi-stroke prefix.
72
72
- `runCommand()` and `dispatchCommand()` execute commands programmatically.
73
73
- Subscribe to `on("state")` for batched change notifications.
74
74
- See [Hosts](/docs/keymap/hosts) for how host focus and target lifecycle affect what is active.
75
75
76
76
## Bindings
77
77
78
-
Bindings are data, not hard-coded event listeners. Each layer contributes binding records that the engine compiles into sequence trees and then projects through focus, priority, runtime conditions and pending-sequence state.
78
+
Bindings are data, not hard-coded event listeners. Each layer contributes binding records that engine compiles into sequence trees and then projects through focus, priority, runtime conditions and pending-sequence state.
79
79
80
80
### Binding shape
81
81
82
-
A binding always has a `key`, and it can also specify `cmd`, `event`, `preventDefault`, `fallthrough` and any custom fields installed by addons or app code.
82
+
binding always has `key`, and it can also specify `cmd`, `event`, `preventDefault`, `fallthrough` and any custom fields installed by addons or app code.
83
83
84
-
- `key` can be a string like `"ctrl+x"`, `"dd"` or `"<leader>s"`, or an object stroke like `{ name: "return", ctrl: true }`.
85
-
- `cmd` can be a named command string or an inline handler.
84
+
- `key` can be string like `"ctrl+x"`, `"dd"` or `"<leader>s"`, or object stroke like `{ name: "return", ctrl: true }`.
85
+
- `cmd` can be named command string or inline handler.
86
86
- `event` defaults to `"press"`; use `"release"` for release bindings.
87
-
- `preventDefault` defaults to `true` and calls `event.preventDefault()` plus `event.stopPropagation()` so the matched key does not reach the host target.
88
-
- `fallthrough` defaults to `false`; setting `true` lets later matching bindings in the same dispatch chain still run after this command. It is independent of `preventDefault`, which controls whether the event escapes the keymap.
87
+
- `preventDefault` defaults to `true` and calls `event.preventDefault()` plus `event.stopPropagation()` so matched key does not reach host target.
88
+
- `fallthrough` defaults to `false`; setting `true` lets later matching bindings in same dispatch chain still run after this command. it's independent of `preventDefault`, which controls whether event escapes keymap.
89
89
90
-
Release bindings are supported, but only for a single stroke. Multi-stroke release bindings such as `"dd"` with `event: "release"` are rejected. Release bindings dispatch on key release, but they do not appear in `getActiveKeys()` because active-key discovery is based on press/pending-sequence state.
90
+
Release bindings are supported, but only for single stroke. Multi-stroke release bindings such as `"dd"` with `event: "release"` are rejected. Release bindings dispatch on key release, but they do not appear in `getActiveKeys()` because active-key discovery is based on press/pending-sequence state.
91
91
92
92
### Parser-driven strings
93
93
94
-
String keys are parser-driven. The engine does not hard-code one binding syntax into the core; it runs registered binding expanders, parsers and transformers to turn binding input into compiled sequences.
94
+
String keys are parser-driven. engine does not hard-code one binding syntax into core; it runs registered binding expanders, parsers and transformers to turn binding input into compiled sequences.
95
95
96
96
- Expanders can rewrite one key string into multiple key strings.
97
-
- Parsers turn a string into one or more normalized strokes.
98
-
- Transformers can rewrite or add parsed bindings before the layer is compiled.
97
+
- Parsers turn string into one or more normalized strokes.
98
+
- Transformers can rewrite or add parsed bindings before layer is compiled.
99
99
100
-
The shared default parser accepts single-stroke named keys, modifier chords, literal punctuation, `" "` for space, `"+"` as a literal plus key, and concatenated multi-stroke sequences such as `"dd"` or `"<leader>s"`.
100
+
shared default parser accepts single-stroke named keys, modifier chords, literal punctuation, `" "` for space, `"+"` as literal plus key, and concatenated multi-stroke sequences such as `"dd"` or `"<leader>s"`.
101
101
102
-
Object-form keys are the escape hatch when you do not want string parsing. `{ name: "return", ctrl: true }` skips the string parser and normalizes directly to a single stroke.
102
+
Object-form keys are escape hatch when you do not want string parsing. `{ name: "return", ctrl: true }` skips string parser and normalizes directly to single stroke.
103
103
104
-
This parser-driven model is why the same engine can support built-in strings like `"ctrl+x"`, tokenized strings like `"<leader>s"`, and addon-defined syntaxes such as bracket tokens or Emacs-style expansions.
104
+
This parser-driven model is why same engine can support built-in strings like `"ctrl+x"`, tokenized strings like `"<leader>s"`, and addon-defined syntaxes such as bracket tokens or Emacs-style expansions.
105
105
106
106
### Tokens
107
107
108
-
Tokens are named single-stroke aliases used inside binding strings. Registering `<leader>` as space lets you write bindings like `"<leader>s"` without repeating the underlying key everywhere.
108
+
Tokens are named single-stroke aliases used inside binding strings. Registering `<leader>` as space lets you write bindings like `"<leader>s"` without repeating underlying key everywhere.
109
109
110
110
```ts
111
111
keymap.registerToken({ name: "<leader>", key: { name: "space" } })
···
115
115
})
116
116
```
117
117
118
-
Tokens are compile-time input syntax, not a separate dispatch mode. They resolve to exactly one stroke, participate in sequence matching like any other stroke, and can be queried with their preserved display form.
118
+
Tokens are compile-time input syntax, not separate dispatch mode. They resolve to exactly one stroke, participate in sequence matching like any other stroke, and can be queried with their preserved display form.
119
119
120
120
### Custom binding fields
121
121
122
-
Bindings can carry custom fields, but those fields only mean something after you register a binding-field compiler with `registerBindingFields()`. A binding field compiler can:
122
+
Bindings can carry custom fields, but those fields only mean something after you register binding-field compiler with `registerBindingFields()`. binding field compiler can:
123
123
124
124
- declare runtime requirements with `require(...)`
125
125
- add runtime matchers with `activeWhen(...)`
···
141
141
})
142
142
```
143
143
144
-
In that example, the binding is only active while `getData("vim.mode")` is `"normal"`, and the compiled binding metadata can expose `{ mode: "normal" }` through query APIs when metadata is requested.
144
+
In that example, binding is only active while `getData("vim.mode")` is `"normal"`, and compiled binding metadata can expose `{ mode: "normal" }` through query APIs when metadata is requested.
145
145
146
-
Unknown custom binding fields are not fatal. If no binding-field compiler is registered for a field, the keymap ignores that field and emits a warning.
146
+
Unknown custom binding fields are not fatal. If no binding-field compiler is registered for field, keymap ignores that field and emits warning.
147
147
148
-
All entry points below use the same registration, dispatch and query model. They only differ in how they provide targets, focus and input events.
148
+
All entry points below use same registration, dispatch and query model. They only differ in how they provide targets, focus and input events.
149
149
150
150
## Commands
151
151
152
-
Named commands are the stable app actions in the system. A layer can register a command with a `name`, a `run()` handler and optional fields like `title`, `desc` or `namespace`, and bindings can point at that command by name. Inline binding handlers work too, but named commands are what power command palettes, search and programmatic execution.
152
+
Named commands are stable app actions in system. layer can register command with `name`, `run()` handler and optional fields like `title`, `desc` or `namespace`, and bindings can point at that command by name. Inline binding handlers work too, but named commands are what power command palettes, search and programmatic execution.
153
153
154
-
Command queries return both raw registration `fields` and any compiled `attrs` produced by command-field addons. `runCommand()` executes the registered command chain directly, while `dispatchCommand()` goes through the active dispatch model and can return `inactive` or `disabled` when that command exists but is not currently dispatchable.
154
+
Command queries return both raw registration `fields` and any compiled `attrs` produced by command-field addons. `runCommand()` executes registered command chain directly, while `dispatchCommand()` goes through active dispatch model and can return `inactive` or `disabled` when that command exists but is not currently dispatchable.
155
155
156
156
## Runtime data
157
157
158
-
Runtime data is the keymap's mutable key-value store. `setData()` and `getData()` let commands, intercepts and matchers share live state such as an editor mode, leader state or search context.
158
+
Runtime data is keymap's mutable key-value store. `setData()` and `getData()` let commands, intercepts and matchers share live state such as editor mode, leader state or search context.
159
159
160
-
That data also drives activation. Layer, binding and command fields can depend on runtime values through `require(...)` and `activeWhen(...)`, so changing a value immediately recomputes what is reachable. If the current pending sequence no longer matches after a data change, the engine clears it.
160
+
That data also drives activation. Layer, binding and command fields can depend on runtime values through `require(...)` and `activeWhen(...)`, so changing value immediately recomputes what is reachable. If current pending sequence no longer matches after data change, engine clears it.
161
161
162
162
## Pending sequences and active keys
163
163
164
-
A pending sequence is the prefix the user has already typed, such as `g` while waiting to see whether the next key completes `gg` or `gd`. `getPendingSequence()` exposes that prefix, and `clearPendingSequence()` / `popPendingSequence()` let addons or app code manage it explicitly.
164
+
pending sequence is prefix user has already typed, such as `g` while waiting to see whether next key completes `gg` or `gd`. `getPendingSequence()` exposes that prefix, and `clearPendingSequence()` / `popPendingSequence()` let addons or app code manage it explicitly.
165
165
166
-
`getActiveKeys()` is the companion query. It does not list every registered binding; it projects the next reachable strokes from the current focus and pending state. That makes it the right API for key hints, which-key style UIs and other live discovery surfaces.
166
+
`getActiveKeys()` is companion query. It does not list every registered binding; it projects next reachable strokes from current focus and pending state. That makes it right API for key hints, which-key style UIs and other live discovery surfaces.
167
167
168
-
- [Hosts](/docs/keymap/hosts) - built-in OpenTUI and HTML adapters plus the `KeymapHost` contract
169
-
- [Core](/docs/keymap/core) - bare `Keymap` and the shared runtime APIs
170
-
- [React](/docs/keymap/react) - provider and hooks for a pre-created OpenTUI keymap
171
-
- [Solid](/docs/keymap/solid) - provider and hooks for a pre-created OpenTUI keymap
168
+
- [Hosts](/docs/keymap/hosts) - built-in OpenTUI and HTML adapters plus `KeymapHost` contract
169
+
- [Core](/docs/keymap/core) - bare `Keymap` and shared runtime APIs
170
+
- [React](/docs/keymap/react) - provider and hooks for pre-created OpenTUI keymap
171
+
- [Solid](/docs/keymap/solid) - provider and hooks for pre-created OpenTUI keymap
172
172
- [Built-in Addons](/docs/keymap/addons) - shipped universal and OpenTUI-specific addons
173
173
- [Custom Addons](/docs/keymap/custom-addons) - public addon-authoring APIs, contexts and constraints
174
174
···
194
194
| `createDefaultOpenTuiKeymap(...)` | OpenTUI keymap plus default keys, enabled fields and metadata fields |
195
195
| `createDefaultHtmlKeymap(...)` | HTML keymap plus default keys, enabled fields, metadata fields and event matching |
196
196
197
-
The default helpers intentionally stay small. Leader tokens, ex commands, timed disambiguation, warning analyzers and OpenTUI textarea helpers are separate addons.
197
+
default helpers intentionally stay small. Leader tokens, ex commands, timed disambiguation, warning analyzers and OpenTUI textarea helpers are separate addons.
198
198
199
199
## Next
200
200
201
-
- [Hosts](/docs/keymap/hosts) explains the built-in host adapters and the `KeymapHost` contract.
202
-
- [Core](/docs/keymap/core) documents the shared runtime, queries, intercepts and extension points.
203
-
- [Built-in Addons](/docs/keymap/addons) covers the shipped addon packages.
204
-
- [Custom Addons](/docs/keymap/custom-addons) covers the public addon-authoring APIs and extension-point constraints.
205
-
- [Hosts](/docs/keymap/hosts), [React](/docs/keymap/react) and [Solid](/docs/keymap/solid) cover the built-in host and framework-specific surfaces.
201
+
- [Hosts](/docs/keymap/hosts) explains built-in host adapters and `KeymapHost` contract.
202
+
- [Core](/docs/keymap/core) documents shared runtime, queries, intercepts and extension points.
203
+
- [Built-in Addons](/docs/keymap/addons) covers shipped addon packages.
204
+
- [Custom Addons](/docs/keymap/custom-addons) covers public addon-authoring APIs and extension-point constraints.
205
+
- [Hosts](/docs/keymap/hosts), [React](/docs/keymap/react) and [Solid](/docs/keymap/solid) cover built-in host and framework-specific surfaces.
+14
-14
skills/opentui/docs/keymap/react.mdx
+14
-14
skills/opentui/docs/keymap/react.mdx
···
1
1
---
2
2
title: React (OpenTUI)
3
-
description: React provider and hooks for a pre-created OpenTUI keymap
3
+
description: React provider and hooks for pre-created OpenTUI keymap
4
4
order: 4
5
5
navTitle: React (OpenTUI)
6
6
---
···
9
9
10
10
This page covers `@opentui/keymap/react`.
11
11
12
-
These bindings are for OpenTUI React apps. They consume a pre-created `Keymap<Renderable, KeyEvent>` from `@opentui/keymap/opentui`; they do not wrap the DOM/HTML adapter used in browser React apps.
12
+
These bindings are for OpenTUI React apps. They consume pre-created `Keymap<Renderable, KeyEvent>` from `@opentui/keymap/opentui`; they do not wrap DOM/HTML adapter used in browser React apps.
13
13
14
-
If you have not read the shared model yet, start with [Keymap overview](/docs/keymap/overview). For keymap construction, see [Keymap hosts](/docs/keymap/hosts).
14
+
If you have not read shared model yet, start with [Keymap overview](/docs/keymap/overview). For keymap construction, see [Keymap hosts](/docs/keymap/hosts).
15
15
16
16
## What React adds
17
17
18
-
- `KeymapProvider` - React context provider for an existing OpenTUI keymap
19
-
- `useKeymap()` - returns the current OpenTUI keymap from context
20
-
- `useBindings(createLayer, deps?)` - registers a keymap layer for the component lifecycle
18
+
- `KeymapProvider` - React context provider for existing OpenTUI keymap
19
+
- `useKeymap()` - returns current OpenTUI keymap from context
20
+
- `useBindings(createLayer, deps?)` - registers keymap layer for component lifecycle
21
21
- `useActiveKeys(options?)` - derived active key list
22
22
- `usePendingSequence()` - derived pending sequence
23
-
- `reactiveMatcherFromStore(subscribe, getSnapshot, predicate?)` - adapts an external store to `ReactiveMatcher`
23
+
- `reactiveMatcherFromStore(subscribe, getSnapshot, predicate?)` - adapts external store to `ReactiveMatcher`
24
24
25
25
## Basic usage
26
26
···
80
80
81
81
## `useBindings`
82
82
83
-
`useBindings()` registers a full `LayerFields<Renderable, KeyEvent>` object. The returned layer can include `priority`, `enabled`, `bindings`, `commands` and any custom addon fields.
83
+
`useBindings()` registers full `LayerFields<Renderable, KeyEvent>` object. returned layer can include `priority`, `enabled`, `bindings`, `commands` and any custom addon fields.
84
84
85
-
React memoizes `createLayer` with `useMemo(createLayer, deps)`. If you omit `deps`, the hook treats the layer factory as static after mount because the default is `[]`. If the layer shape depends on props or React state, include those values in `deps`.
85
+
React memoizes `createLayer` with `useMemo(createLayer, deps)`. If you omit `deps`, hook treats layer factory as static after mount because default is `[]`. If layer shape depends on props or React state, include those values in `deps`.
86
86
87
87
React-specific layer shapes:
88
88
···
93
93
| Local exact-focus layer | Set `targetRef` and `targetMode: "focus"` |
94
94
95
95
- When `targetRef` is present and `targetMode` is omitted, `focus-within` is used.
96
-
- If `targetRef.current` is `null`, registration waits until the ref resolves.
97
-
- Passing a local `targetMode` without `targetRef` throws.
98
-
- `deps` controls when the layer factory is re-evaluated.
99
-
- Local layers follow `targetRef.current`, so they can wait for a ref to mount and retarget if that ref later points at a different renderable.
96
+
- If `targetRef.current` is `null`, registration waits until ref resolves.
97
+
- Passing local `targetMode` without `targetRef` throws.
98
+
- `deps` controls when layer factory is re-evaluated.
99
+
- Local layers follow `targetRef.current`, so they can wait for ref to mount and retarget if that ref later points at different renderable.
100
100
101
101
## `useActiveKeys()` and `usePendingSequence()`
102
102
···
109
109
110
110
## `reactiveMatcherFromStore()`
111
111
112
-
Use this when an addon field expects a `ReactiveMatcher`, for example the shipped `enabled` field:
112
+
Use this when addon field expects `ReactiveMatcher`, for example shipped `enabled` field:
113
113
114
114
```tsx
115
115
const matcher = useMemo(
+15
-15
skills/opentui/docs/keymap/solid.mdx
+15
-15
skills/opentui/docs/keymap/solid.mdx
···
1
1
---
2
2
title: Solid (OpenTUI)
3
-
description: Solid provider and hooks for a pre-created OpenTUI keymap
3
+
description: Solid provider and hooks for pre-created OpenTUI keymap
4
4
order: 5
5
5
navTitle: Solid (OpenTUI)
6
6
---
···
9
9
10
10
This page covers `@opentui/keymap/solid`.
11
11
12
-
These bindings are for OpenTUI Solid apps. They consume a pre-created `Keymap<Renderable, KeyEvent>` from `@opentui/keymap/opentui`; they do not wrap the DOM/HTML adapter used in browser Solid apps.
12
+
These bindings are for OpenTUI Solid apps. They consume pre-created `Keymap<Renderable, KeyEvent>` from `@opentui/keymap/opentui`; they do not wrap DOM/HTML adapter used in browser Solid apps.
13
13
14
-
If you have not read the shared model yet, start with [Keymap overview](/docs/keymap/overview). For keymap construction, see [Keymap hosts](/docs/keymap/hosts).
14
+
If you have not read shared model yet, start with [Keymap overview](/docs/keymap/overview). For keymap construction, see [Keymap hosts](/docs/keymap/hosts).
15
15
16
16
## What Solid adds
17
17
18
-
- `KeymapProvider` - Solid context provider for an existing OpenTUI keymap
19
-
- `useKeymap()` - returns the current OpenTUI keymap from context
20
-
- `useBindings(createLayer)` - registers a keymap layer for the current reactive scope
21
-
- `useKeymapSelector(selector)` - reactively derives any value from the current keymap
22
-
- `reactiveMatcherFromSignal(accessor, predicate?)` - adapts a Solid accessor to `ReactiveMatcher`
18
+
- `KeymapProvider` - Solid context provider for existing OpenTUI keymap
19
+
- `useKeymap()` - returns current OpenTUI keymap from context
20
+
- `useBindings(createLayer)` - registers keymap layer for current reactive scope
21
+
- `useKeymapSelector(selector)` - reactively derives any value from current keymap
22
+
- `reactiveMatcherFromSignal(accessor, predicate?)` - adapts Solid accessor to `ReactiveMatcher`
23
23
24
24
## Basic usage
25
25
···
76
76
77
77
## `useBindings`
78
78
79
-
`useBindings()` registers a full `LayerFields<Renderable, KeyEvent>` object. The returned layer can include `priority`, `enabled`, `bindings`, `commands` and any custom addon fields.
79
+
`useBindings()` registers full `LayerFields<Renderable, KeyEvent>` object. returned layer can include `priority`, `enabled`, `bindings`, `commands` and any custom addon fields.
80
80
81
-
Solid runs `createLayer()` inside a reactive `createEffect`. Any tracked signals or memos you read inside the factory become dependencies, so the hook will unregister and re-register the layer when those values change. If the factory does not read reactive values, the layer stays stable.
81
+
Solid runs `createLayer()` inside reactive `createEffect`. Any tracked signals or memos you read inside factory become dependencies, so hook will unregister and re-register layer when those values change. If factory does not read reactive values, layer stays stable.
82
82
83
83
Solid-specific layer shapes:
84
84
···
89
89
| Local exact-focus layer | Set `target` accessor and `targetMode: "focus"` |
90
90
91
91
- When `target` is present and `targetMode` is omitted, `focus-within` is used.
92
-
- If the target accessor returns `undefined`, registration waits until it resolves.
93
-
- Passing a local `targetMode` without `target` throws.
92
+
- If target accessor returns `undefined`, registration waits until it resolves.
93
+
- Passing local `targetMode` without `target` throws.
94
94
95
95
## `useKeymapSelector()`
96
96
97
-
`useKeymapSelector()` is the general derived-read API for Solid. It returns an `Accessor<T>`, so you read the current value by calling it:
97
+
`useKeymapSelector()` is general derived-read API for Solid. It returns `Accessor<T>`, so you read current value by calling it:
98
98
99
99
```tsx
100
100
const activeKeys = useKeymapSelector((keymap) => keymap.getActiveKeys({ includeMetadata: true }))
···
106
106
107
107
Use it for command palettes, key hint UIs, leader prompts, status bars, or any other derived keymap view.
108
108
109
-
When the underlying host is destroyed mid-update, `useKeymapSelector()` returns the previous accessor value instead of throwing, so subscribers can render once more before their owner cleans up. The first read still throws if the host is already gone.
109
+
When underlying host is destroyed mid-update, `useKeymapSelector()` returns previous accessor value instead of throwing, so subscribers can render once more before their owner cleans up. first read still throws if host is already gone.
110
110
111
111
## `reactiveMatcherFromSignal()`
112
112
113
-
Use this when an addon field expects a `ReactiveMatcher`, for example the shipped `enabled` field:
113
+
Use this when addon field expects `ReactiveMatcher`, for example shipped `enabled` field:
114
114
115
115
```tsx
116
116
useBindings(() => ({
+21
-21
skills/opentui/docs/plugins/core.mdx
+21
-21
skills/opentui/docs/plugins/core.mdx
···
6
6
7
7
# Core slots
8
8
9
-
This page shows the core host API for plugin slots.
9
+
This page shows core host API for plugin slots.
10
10
11
-
Use slots when you want external modules to render `BaseRenderable` UI in host-defined layout regions without forking the app. The host keeps control of layout and slot typing; plugins only render through the APIs you expose.
11
+
Use slots when you want external modules to render `BaseRenderable` UI in host-defined layout regions without forking app. host keeps control of layout and slot typing; plugins only render through APIs you expose.
12
12
13
-
If you have not read the shared model yet, start with [Plugin Slots](/docs/plugins/slots).
13
+
If you have not read shared model yet, start with [Plugin Slots](/docs/plugins/slots).
14
14
15
15
## What core adds
16
16
17
17
On top of `createSlotRegistry`, core provides:
18
18
19
-
- `createCoreSlotRegistry` — create a registry typed for `BaseRenderable` nodes
20
-
- `registerCorePlugin` — register a plugin using the core-specific `CorePlugin` interface
21
-
- `SlotRenderable` — a `Renderable` that mounts a slot into the renderable tree
19
+
- `createCoreSlotRegistry` — create registry typed for `BaseRenderable` nodes
20
+
- `registerCorePlugin` — register plugin using core-specific `CorePlugin` interface
21
+
- `SlotRenderable` — `Renderable` that mounts slot into renderable tree
22
22
- `resolveCoreSlot` — resolve slot entries without mounting
23
23
- `@opentui/core/runtime-plugin-support` / `createRuntimePlugin` — runtime module support for external plugin/module loading in Bun
24
24
25
-
Core slot renderers receive both the host context and slot data: `(ctx, data) => BaseRenderable`.
25
+
Core slot renderers receive both host context and slot data: `(ctx, data) => BaseRenderable`.
26
26
27
-
`createCoreSlotRegistry` accepts the same [`SlotRegistryOptions`](/docs/plugins/slots#registry-options) as `createSlotRegistry`.
27
+
`createCoreSlotRegistry` accepts same [`SlotRegistryOptions`](/docs/plugins/slots#registry-options) as `createSlotRegistry`.
28
28
29
29
## Runtime-loaded external plugins
30
30
···
34
34
import "@opentui/core/runtime-plugin-support"
35
35
```
36
36
37
-
This installs Bun runtime support for `@opentui/core` plus default core runtime entrypoints (`@opentui/core/testing`). Add first-party package runtime modules explicitly when a plugin imports them.
37
+
This installs Bun runtime support for `@opentui/core` plus default core runtime entrypoints (`@opentui/core/testing`). Add first-party package runtime modules explicitly when plugin imports them.
38
38
39
-
If you need additional host-resolved modules, configure runtime support before the side-effect import is loaded:
39
+
If you need additional host-resolved modules, configure runtime support before side-effect import is loaded:
40
40
41
41
```ts
42
42
const { ensureRuntimePluginSupport } = await import("@opentui/core/runtime-plugin-support/configure")
···
48
48
})
49
49
```
50
50
51
-
For plugins that import `@opentui/three`, install `@opentui/three` in the host app and pass its runtime module map:
51
+
For plugins that import `@opentui/three`, install `@opentui/three` in host app and pass its runtime module map:
52
52
53
53
```ts
54
54
import { runtimeModules as threeRuntimeModules } from "@opentui/three/runtime-modules"
···
59
59
})
60
60
```
61
61
62
-
The side-effect import and configurable entrypoint install the same runtime plugin. Late additions throw with a clear error instead of being ignored.
62
+
side-effect import and configurable entrypoint install same runtime plugin. Late additions throw with clear error instead of being ignored.
63
63
64
64
## `CorePlugin` interface
65
65
···
71
71
| `dispose` | `() => void` | no | Called when the plugin is unregistered or the registry is cleared. |
72
72
| `slots` | `Partial<Record<SlotName, CoreSlotContribution>>` | yes | Each value is a renderer function or a [managed slot object](#managed-slot-contributions). |
73
73
74
-
A `CoreSlotContribution` is either a plain renderer `(ctx, data) => BaseRenderable` or a `CoreManagedSlot` with lifecycle hooks.
74
+
`CoreSlotContribution` is either plain renderer `(ctx, data) => BaseRenderable` or `CoreManagedSlot` with lifecycle hooks.
75
75
76
76
## Basic usage
77
77
78
-
A `SlotRenderable` extends `Renderable`, so it can be added to any parent like a `BoxRenderable`. It resolves plugins from the registry, manages their lifecycle, and reconciles their output as its children.
78
+
`SlotRenderable` extends `Renderable`, so it can be added to any parent like `BoxRenderable`. It resolves plugins from registry, manages their lifecycle, and reconciles their output as its children.
79
79
80
80
```typescript
81
81
import {
···
133
133
slot.destroy()
134
134
```
135
135
136
-
`registerCorePlugin` returns an unregister function (`() => void`). Calling it removes the plugin and invokes its `dispose` hook.
136
+
`registerCorePlugin` returns unregister function (`() => void`). Calling it removes plugin and invokes its `dispose` hook.
137
137
138
-
Because `SlotRenderable` extends `Renderable`, it accepts all standard layout options (`width`, `height`, `flexDirection`, `padding`, etc.) alongside the slot-specific options.
138
+
Because `SlotRenderable` extends `Renderable`, it accepts all standard layout options (`width`, `height`, `flexDirection`, `padding`, etc.) alongside slot-specific options.
139
139
140
140
## `SlotRenderable` options
141
141
···
160
160
161
161
## `resolveCoreSlot`
162
162
163
-
Resolve slot entries without mounting them. Useful when you need to inspect or render plugin output manually.
163
+
Resolve slot entries without mounting them. Useful when need to inspect or render plugin output manually.
164
164
165
165
```typescript
166
166
import { createCliRenderer, createCoreSlotRegistry, resolveCoreSlot } from "@opentui/core"
···
177
177
178
178
## Plugin failure placeholders
179
179
180
-
If a plugin throws during slot render, you can provide host-controlled fallback UI for that plugin failure:
180
+
If plugin throws during slot render, provide host-controlled fallback UI for that plugin failure:
181
181
182
182
```typescript
183
183
const slot = new SlotRenderable(renderer, {
···
195
195
196
196
## Managed slot contributions
197
197
198
-
A core slot contribution can be a plain function or a managed slot object with lifecycle hooks:
198
+
core slot contribution can be plain function or managed slot object with lifecycle hooks:
199
199
200
200
```typescript
201
201
registerCorePlugin(registry, {
···
230
230
231
231
### Node ownership
232
232
233
-
When a slot contribution is a **plain function**, the host owns the returned nodes. On deactivation or disposal, the host detaches and destroys them.
233
+
When slot contribution is **plain function**, host owns returned nodes. On deactivation or disposal, host detaches and destroys them.
234
234
235
-
When a slot contribution is a **managed slot object**, the plugin owns the nodes. On deactivation the host detaches them but does _not_ destroy them — the plugin can reuse them if it becomes active again. On disposal, `onDispose` is called so the plugin can clean up.
235
+
When slot contribution is **managed slot object**, plugin owns nodes. On deactivation host detaches them but does _not_ destroy them — plugin can reuse them if it becomes active again. On disposal, `onDispose` is called so plugin can clean up.
236
236
237
237
## Observability
238
238
+14
-14
skills/opentui/docs/plugins/react.mdx
+14
-14
skills/opentui/docs/plugins/react.mdx
···
1
1
---
2
2
title: React
3
-
description: React slot components backed by the shared plugin registry
3
+
description: React slot components backed by shared plugin registry
4
4
order: 3
5
5
---
6
6
···
8
8
9
9
This page shows React integration for plugin slots.
10
10
11
-
Use slots when you want external modules to contribute `ReactNode` UI in host-defined regions without forking your app. The host keeps ownership of layout and slot typing; plugins only see the context and props you expose.
11
+
Use slots when you want external modules to contribute `ReactNode` UI in host-defined regions without forking your app. host keeps ownership of layout and slot typing; plugins only see context and props you expose.
12
12
13
-
If you have not read the shared model yet, start with [Plugin Slots](/docs/plugins/slots).
13
+
If you have not read shared model yet, start with [Plugin Slots](/docs/plugins/slots).
14
14
15
15
## Runtime-loaded external plugins
16
16
···
20
20
import "@opentui/react/runtime-plugin-support"
21
21
```
22
22
23
-
This installs Bun runtime support so external TS/TSX plugin modules resolve against the host runtime instances (`@opentui/react`, React JSX runtime modules, and core runtime modules).
23
+
This installs Bun runtime support so external TS/TSX plugin modules resolve against host runtime instances (`@opentui/react`, React JSX runtime modules, and core runtime modules).
24
24
25
25
Use this for plugin systems in both normal Bun runs and standalone compiled executables.
26
26
···
31
31
registry.register(mod.loadExternalPlugin())
32
32
```
33
33
34
-
If plugins need additional host-resolved modules, configure runtime support before the side-effect import is loaded:
34
+
If plugins need additional host-resolved modules, configure runtime support before side-effect import is loaded:
35
35
36
36
```ts
37
37
import { ensureRuntimePluginSupport } from "@opentui/react/runtime-plugin-support/configure"
···
43
43
})
44
44
```
45
45
46
-
First-party packages expose side-effect-free runtime module maps. For plugins that import `@opentui/three`, install `@opentui/three` in the host app and pass its runtime modules explicitly:
46
+
First-party packages expose side-effect-free runtime module maps. For plugins that import `@opentui/three`, install `@opentui/three` in host app and pass its runtime modules explicitly:
47
47
48
48
```ts
49
49
import { runtimeModules as threeRuntimeModules } from "@opentui/three/runtime-modules"
···
54
54
})
55
55
```
56
56
57
-
The side-effect import and configurable entrypoint install the same runtime plugin. Late additions throw with a clear error instead of being ignored.
57
+
side-effect import and configurable entrypoint install same runtime plugin. Late additions throw with clear error instead of being ignored.
58
58
59
59
## What React adds
60
60
61
-
- `createReactSlotRegistry(renderer, context, options?)` — create a registry typed for `ReactNode`. Accepts the same [`SlotRegistryOptions`](/docs/plugins/slots#registry-options) as `createSlotRegistry`.
62
-
- `Slot<TSlots, TContext>` — generic slot component that takes `registry` as a required prop
63
-
- `createSlot(registry, options?)` — optional convenience helper that returns a registry-bound `<Slot />` component
64
-
- `ReactPlugin<TSlots, TContext>` — convenience type alias for a plugin that returns `ReactNode`
61
+
- `createReactSlotRegistry(renderer, context, options?)` — create registry typed for `ReactNode`. Accepts same [`SlotRegistryOptions`](/docs/plugins/slots#registry-options) as `createSlotRegistry`.
62
+
- `Slot<TSlots, TContext>` — generic slot component that takes `registry` as required prop
63
+
- `createSlot(registry, options?)` — optional convenience helper that returns registry-bound `<Slot />` component
64
+
- `ReactPlugin<TSlots, TContext>` — convenience type alias for plugin that returns `ReactNode`
65
65
- `@opentui/react/runtime-plugin-support` — one-line runtime support for external plugin/module loading
66
66
- `@opentui/react/runtime-plugin-support/configure` — configurable runtime support without import-time side effects
67
67
···
106
106
107
107
## Optional convenience helper
108
108
109
-
If you prefer not to pass `registry` each time, you can still bind one once:
109
+
If you prefer not to pass `registry` each time, still bind one once:
110
110
111
111
```tsx
112
112
const AppSlot = createSlot(registry)
···
139
139
})
140
140
```
141
141
142
-
If a plugin throws, the slot renders the placeholder. If no placeholder is provided (or it returns `null`), the slot falls back to `children`.
142
+
If plugin throws, slot renders placeholder. If no placeholder is provided (or it returns `null`), slot falls back to `children`.
143
143
144
-
Plugins that throw during the initial render call are caught inline. Plugins that throw during a React re-render are caught by an internal error boundary that resets on registry changes.
144
+
Plugins that throw during initial render call are caught inline. Plugins that throw during React re-render are caught by internal error boundary that resets on registry changes.
145
145
146
146
## Observability
147
147
+25
-25
skills/opentui/docs/plugins/slots.mdx
+25
-25
skills/opentui/docs/plugins/slots.mdx
···
4
4
order: 1
5
5
navTitle: Overview
6
6
skill:
7
-
entry: true
8
-
intents: [plugins, plugin, slots, registry, extensions]
7
+
entry: true
8
+
intents: [plugins, plugin, slots, registry, extensions]
9
9
---
10
10
11
11
# Plugin slots
12
12
13
-
Most TUI apps start as one codebase. As features and teams grow, you may want extension points without asking users to fork the app.
13
+
Most TUI apps start as one codebase. As features and teams grow, want extension points without asking users to fork app.
14
14
15
-
Plugin slots give you that. The host application defines named places in the layout (for example, a status bar, sidebar, or panel), and plugins contribute UI for those places at runtime.
15
+
Plugin slots give you that. host application defines named places in layout (for example, status bar, sidebar, or panel), and plugins contribute UI for those places at runtime.
16
16
17
-
The host stays in control of layout, rendering mode, and type contracts. Plugins only receive the context and slot props the host intentionally exposes.
17
+
host stays in control of layout, rendering mode, and type contracts. Plugins only receive context and slot props host intentionally exposes.
18
18
19
-
This page describes the **shared registry API** that the core, React, and Solid bindings are built on. If you are building an app, start with the page for the binding you use:
19
+
This page describes **shared registry API** that core, React, and Solid bindings are built on. If you are building app, start with page for binding you use:
20
20
21
21
- [Core slots](/docs/plugins/core) — framework-free, `BaseRenderable` nodes
22
22
- [React slots](/docs/plugins/react) — `ReactNode`
23
23
- [Solid slots](/docs/plugins/solid) — `JSX.Element`
24
24
25
-
If you load plugin modules from disk at runtime, see the runtime support notes on the [React slots page](/docs/plugins/react#runtime-loaded-external-plugins) and [Solid slots page](/docs/plugins/solid#runtime-loaded-external-plugins). For custom hosts, use `@opentui/core/runtime-plugin-support` or `createRuntimePlugin` from `@opentui/core/runtime-plugin`.
25
+
If you load plugin modules from disk at runtime, see runtime support notes on [React slots page](/docs/plugins/react#runtime-loaded-external-plugins) and [Solid slots page](/docs/plugins/solid#runtime-loaded-external-plugins). For custom hosts, use `@opentui/core/runtime-plugin-support` or `createRuntimePlugin` from `@opentui/core/runtime-plugin`.
26
26
27
-
Read on if you need to understand the underlying model, want to build a custom binding for another framework, or need direct access to the registry API.
27
+
Read on if need to understand underlying model, want to build custom binding for another framework, or need direct access to registry API.
28
28
29
29
## Concepts
30
30
31
31
- **Host**: defines slot names and slot prop types.
32
32
- **Plugin**: contributes one or more slot renderer callbacks. May include lifecycle hooks.
33
-
- **Registry**: registers plugins and resolves contributions for a slot.
33
+
- **Registry**: registers plugins and resolves contributions for slot.
34
34
- **Slot mode**: controls how plugin output and fallback UI combine (`append`, `replace`, or `single_winner`).
35
35
36
36
## Define slots and host context
37
37
38
-
Slot names map to the props each slot receives. The host context is a shared object passed to every plugin renderer.
38
+
Slot names map to props each slot receives. host context is shared object passed to every plugin renderer.
39
39
40
40
```typescript
41
41
import type { PluginContext } from "@opentui/core"
···
51
51
}
52
52
```
53
53
54
-
The context can be any object. `PluginContext` is a type alias for `object` — extending it is not required but gives your plugins a named type to reference.
54
+
context can be any object. `PluginContext` is type alias for `object` — extending it's not required but gives your plugins named type to reference.
55
55
56
56
## Create a registry
57
57
···
68
68
const registry = createSlotRegistry<string, AppSlots, typeof context>(renderer, "my-app:plugins", context)
69
69
```
70
70
71
-
The first type parameter (`TNode`) is the node type your framework returns — `BaseRenderable` for core, `ReactNode` for React, `JSX.Element` for Solid. The framework-specific helpers fill this in for you.
71
+
first type parameter (`TNode`) is node type your framework returns — `BaseRenderable` for core, `ReactNode` for React, `JSX.Element` for Solid. framework-specific helpers fill this in for you.
72
72
73
-
`createSlotRegistry` is renderer-scoped. For a given `(renderer, key)` pair, you always get the same registry instance. The `key` parameter namespaces registries within a renderer so multiple independent registries can coexist.
73
+
`createSlotRegistry` is renderer-scoped. For given `(renderer, key)` pair, you always get same registry instance. `key` parameter namespaces registries within renderer so multiple independent registries can coexist.
74
74
75
-
Calling `createSlotRegistry` again with the same `(renderer, key)` pair returns the existing registry and applies the new `options` via `configure()`. The `context` argument **must** be the same object reference — passing a different context object throws an error. This means you should create the context object once and reuse it:
75
+
Calling `createSlotRegistry` again with same `(renderer, key)` pair returns existing registry and applies new `options` via `configure()`. `context` argument **must** be same object reference — passing different context object throws error. This means create context object once and reuse it:
76
76
77
77
```typescript
78
78
// correct — same object reference
···
84
84
const reg3 = createSlotRegistry(renderer, "my-key", { appName: "my-app" })
85
85
```
86
86
87
-
When the renderer is destroyed, all registries scoped to it are automatically cleared and disposed.
87
+
When renderer is destroyed, all registries scoped to it are automatically cleared and disposed.
88
88
89
-
The framework-specific helpers (`createCoreSlotRegistry`, `createReactSlotRegistry`, `createSolidSlotRegistry`) call `createSlotRegistry` internally with a fixed key. Use `createSlotRegistry` directly only if you need multiple independent registries per renderer.
89
+
framework-specific helpers (`createCoreSlotRegistry`, `createReactSlotRegistry`, `createSolidSlotRegistry`) call `createSlotRegistry` internally with fixed key. Use `createSlotRegistry` directly only if you need multiple independent registries per renderer.
90
90
91
91
### Registry options
92
92
93
-
All `create*SlotRegistry` functions accept an optional `SlotRegistryOptions` object:
93
+
All `create*SlotRegistry` functions accept optional `SlotRegistryOptions` object:
94
94
95
95
| Option | Type | Default | Description |
96
96
| ------------------- | ----------------------------------- | ------- | ----------------------------------------------------------- |
···
121
121
unregister()
122
122
```
123
123
124
-
`register()` returns an unregister function. Calling it removes the plugin and invokes its `dispose` hook.
124
+
`register()` returns unregister function. Calling it removes plugin and invokes its `dispose` hook.
125
125
126
126
### Plugin interface
127
127
···
133
133
| `dispose` | `() => void` | no | Called when the plugin is unregistered or the registry is cleared. |
134
134
| `slots` | `{ [slotName]: (ctx, props) => TNode }` | yes | Slot renderer callbacks. Each receives the host context and slot-specific props. |
135
135
136
-
The core binding extends this with [managed slot objects](/docs/plugins/core#managed-slot-contributions) that add lifecycle hooks.
136
+
core binding extends this with [managed slot objects](/docs/plugins/core#managed-slot-contributions) that add lifecycle hooks.
137
137
138
138
### Ordering
139
139
···
145
145
146
146
## Slot modes
147
147
148
-
Every slot mount or `<Slot>` component accepts a `mode`. The mode controls how plugin output and fallback UI combine.
148
+
Every slot mount or `<Slot>` component accepts `mode`. mode controls how plugin output and fallback UI combine.
149
149
150
150
| Mode | Behavior |
151
151
| --------------- | -------------------------------------------------------------------------- |
···
163
163
// Array<(ctx, props) => TNode>
164
164
```
165
165
166
-
`renderer` here means the plugin's **slot renderer callback**, not the `CliRenderer` instance.
166
+
`renderer` here means plugin's **slot renderer callback**, not `CliRenderer` instance.
167
167
168
-
Use `resolveEntries` when you need plugin ids alongside the callbacks. Use `resolve` when you only need the callbacks.
168
+
Use `resolveEntries` when you need plugin ids alongside callbacks. Use `resolve` when you only need callbacks.
169
169
170
170
## Registry methods
171
171
···
196
196
})
197
197
```
198
198
199
-
You can also read and clear buffered errors:
199
+
also read and clear buffered errors:
200
200
201
201
```typescript
202
202
const history = registry.getPluginErrors()
···
205
205
206
206
### PluginErrorReport
207
207
208
-
The `reportPluginError` method accepts a `PluginErrorReport`:
208
+
`reportPluginError` method accepts `PluginErrorReport`:
209
209
210
210
| Field | Type | Required | Description |
211
211
| ---------- | --------------------- | -------- | ------------------------------------------------------------ |
···
228
228
229
229
## Next: concrete host APIs
230
230
231
-
Use the shared model above with one of these host integrations:
231
+
Use shared model above with one of these host integrations:
232
232
233
233
- [Core slots](/docs/plugins/core) — framework-free, returns `BaseRenderable` nodes
234
234
- [React slots](/docs/plugins/react) — returns `ReactNode`
+14
-14
skills/opentui/docs/plugins/solid.mdx
+14
-14
skills/opentui/docs/plugins/solid.mdx
···
1
1
---
2
2
title: Solid
3
-
description: Solid slot components backed by the shared plugin registry
3
+
description: Solid slot components backed by shared plugin registry
4
4
order: 4
5
5
---
6
6
···
8
8
9
9
This page shows Solid integration for plugin slots.
10
10
11
-
Use slots when you want external modules to contribute `JSX.Element` UI in host-defined regions without forking your app. The host keeps ownership of layout and slot typing; plugins only see the context and props you expose.
11
+
Use slots when you want external modules to contribute `JSX.Element` UI in host-defined regions without forking your app. host keeps ownership of layout and slot typing; plugins only see context and props you expose.
12
12
13
-
If you have not read the shared model yet, start with [Plugin Slots](/docs/plugins/slots).
13
+
If you have not read shared model yet, start with [Plugin Slots](/docs/plugins/slots).
14
14
15
15
## Runtime-loaded external plugins
16
16
···
20
20
import "@opentui/solid/runtime-plugin-support"
21
21
```
22
22
23
-
This is a Bun drop-in that installs runtime transform support so external TS/TSX plugin modules use the same runtime instances as the host app (`@opentui/solid`, `@opentui/core`, `@opentui/core/testing`, `solid-js`, and `solid-js/store`). If a plugin imports another OpenTUI package, provide that package through `additional` runtime modules.
23
+
This is Bun drop-in that installs runtime transform support so external TS/TSX plugin modules use same runtime instances as host app (`@opentui/solid`, `@opentui/core`, `@opentui/core/testing`, `solid-js`, and `solid-js/store`). If plugin imports another OpenTUI package, provide that package through `additional` runtime modules.
24
24
25
25
Use this for plugin systems in both normal Bun runs and standalone compiled executables.
26
26
···
31
31
registry.register(mod.loadExternalPlugin())
32
32
```
33
33
34
-
If plugins need additional host-resolved modules, configure runtime support before the side-effect import is loaded:
34
+
If plugins need additional host-resolved modules, configure runtime support before side-effect import is loaded:
35
35
36
36
```ts
37
37
import { ensureRuntimePluginSupport } from "@opentui/solid/runtime-plugin-support/configure"
···
54
54
})
55
55
```
56
56
57
-
For plugins that import `@opentui/three`, install `@opentui/three` in the host app and pass its runtime modules explicitly:
57
+
For plugins that import `@opentui/three`, install `@opentui/three` in host app and pass its runtime modules explicitly:
58
58
59
59
```ts
60
60
import { runtimeModules as threeRuntimeModules } from "@opentui/three/runtime-modules"
···
65
65
})
66
66
```
67
67
68
-
The side-effect import and configurable entrypoint install the same runtime plugin. Late additions throw with a clear error instead of being ignored.
68
+
side-effect import and configurable entrypoint install same runtime plugin. Late additions throw with clear error instead of being ignored.
69
69
70
70
## What Solid adds
71
71
72
-
- `createSolidSlotRegistry(renderer, context, options?)` — create a registry typed for `JSX.Element`. Accepts the same [`SlotRegistryOptions`](/docs/plugins/slots#registry-options) as `createSlotRegistry`.
73
-
- `Slot<TSlots, TContext>` — generic slot component that takes `registry` as a required prop
74
-
- `createSlot(registry, options?)` — optional convenience helper that returns a registry-bound `<Slot />` component
75
-
- `SolidPlugin<TSlots, TContext>` — convenience type alias for a plugin that returns `JSX.Element`
72
+
- `createSolidSlotRegistry(renderer, context, options?)` — create registry typed for `JSX.Element`. Accepts same [`SlotRegistryOptions`](/docs/plugins/slots#registry-options) as `createSlotRegistry`.
73
+
- `Slot<TSlots, TContext>` — generic slot component that takes `registry` as required prop
74
+
- `createSlot(registry, options?)` — optional convenience helper that returns registry-bound `<Slot />` component
75
+
- `SolidPlugin<TSlots, TContext>` — convenience type alias for plugin that returns `JSX.Element`
76
76
- `@opentui/solid/runtime-plugin-support` — one-line runtime support for external plugin/module loading
77
77
- `@opentui/solid/runtime-plugin-support/configure` — configurable runtime support without import-time side effects
78
78
···
115
115
116
116
## Optional convenience helper
117
117
118
-
If you prefer not to pass `registry` each time, you can still bind one once:
118
+
If you prefer not to pass `registry` each time, still bind one once:
119
119
120
120
```tsx
121
121
const AppSlot = createSlot(registry)
···
148
148
})
149
149
```
150
150
151
-
If a plugin throws, the slot renders the placeholder. If no placeholder is provided (or it returns `null`), the slot falls back to `children`.
151
+
If plugin throws, slot renders placeholder. If no placeholder is provided (or it returns `null`), slot falls back to `children`.
152
152
153
-
Plugins that throw during the initial render call are caught inline. Plugins that throw during a Solid re-render are caught by an internal `<ErrorBoundary>` that reports the error to the registry.
153
+
Plugins that throw during initial render call are caught inline. Plugins that throw during Solid re-render are caught by internal `<ErrorBoundary>` that reports error to registry.
154
154
155
155
## Observability
156
156
+7
-7
skills/opentui/docs/reference/color-matrix.mdx
+7
-7
skills/opentui/docs/reference/color-matrix.mdx
···
9
9
`FrameBuffer` supports native 4x4 RGBA matrix transforms through two methods: `colorMatrix(...)` and
10
10
`colorMatrixUniform(...)`.
11
11
12
-
Use `colorMatrix(...)` when you want to transform specific cells with per-cell strengths. Use
13
-
`colorMatrixUniform(...)` when you want to apply one transform to the entire buffer.
12
+
Use `colorMatrix(...)` when want to transform specific cells with per-cell strengths. Use
13
+
`colorMatrixUniform(...)` when want to apply one transform to entire buffer.
14
14
15
15
Both methods work on normalized RGBA values (`0.0` to `1.0`) and can target foreground, background, or both channels.
16
16
···
57
57
58
58
## Target channels
59
59
60
-
Use the `TargetChannel` enum to choose which color buffers are affected:
60
+
Use `TargetChannel` enum to choose which color buffers are affected:
61
61
62
62
- `TargetChannel.FG` (`1`): foreground only
63
63
- `TargetChannel.BG` (`2`): background only
···
73
73
74
74
- `x` and `y` are cell coordinates
75
75
- `perCellStrength` is multiplied by method `strength`
76
-
- incomplete trailing values (not a multiple of 3) are ignored
76
+
- incomplete trailing values (not multiple of 3) are ignored
77
77
- out-of-bounds or non-finite coordinates are skipped
78
78
- non-finite effective strengths are skipped
79
79
80
-
This method is useful for effects that only affect part of the buffer, such as scanlines, vignettes, or localized color
80
+
This method is useful for effects that only affect part of buffer, such as scanlines, vignettes, or localized color
81
81
grading.
82
82
83
83
## `colorMatrixUniform` behavior
84
84
85
-
`colorMatrixUniform` applies the same matrix to every pixel in the selected channel(s).
85
+
`colorMatrixUniform` applies same matrix to every pixel in selected channel(s).
86
86
87
-
- optimized path processes 4 pixels at a time with SIMD
87
+
- optimized path processes 4 pixels at time with SIMD
88
88
- scalar fallback handles any remaining pixels
89
89
- `strength === 0` or non-finite `strength` returns early
90
90
+7
-7
skills/opentui/docs/reference/env-vars.mdx
+7
-7
skills/opentui/docs/reference/env-vars.mdx
···
3
3
description: Runtime configuration flags for OpenTUI
4
4
order: 1
5
5
skill:
6
-
entry: true
7
-
intents: [env, environment, configuration, flags]
6
+
entry: true
7
+
intents: [env, environment, configuration, flags]
8
8
---
9
9
10
10
# Environment variables
11
11
12
-
OpenTUI reads environment variables at runtime. Bun loads `.env` automatically, so you can set these in your shell or in a `.env` file.
12
+
OpenTUI reads environment variables at runtime. Bun loads `.env` automatically, so set these in your shell or in `.env` file.
13
13
14
14
## Variables
15
15
···
37
37
## Notes
38
38
39
39
- `OPENTUI_FORCE_EXPLICIT_WIDTH=false` skips OSC 66 queries on older terminals.
40
-
- `OTUI_PALETTE_IDLE_TIMEOUT_MS` bounds palette detection when a terminal reports OSC support but does not answer follow-up color queries.
41
-
- Disable global `console.*` capture with `OTUI_USE_CONSOLE=false`. `consoleMode` only changes the overlay surface.
42
-
- `OTUI_NO_NATIVE_RENDER` still runs the render loop. In `"split-footer"` mode, the current stdout flush path can still emit ANSI cursor movement and clear sequences.
43
-
- `OTUI_DUMP_CAPTURES` runs from the renderer exit handler. A direct `renderer.destroy()` call does not trigger it by itself.
40
+
- `OTUI_PALETTE_IDLE_TIMEOUT_MS` bounds palette detection when terminal reports OSC support but does not answer follow-up color queries.
41
+
- Disable global `console.*` capture with `OTUI_USE_CONSOLE=false`. `consoleMode` only changes overlay surface.
42
+
- `OTUI_NO_NATIVE_RENDER` still runs render loop. In `"split-footer"` mode, current stdout flush path can still emit ANSI cursor movement and clear sequences.
43
+
- `OTUI_DUMP_CAPTURES` runs from renderer exit handler. direct `renderer.destroy()` call does not trigger it by itself.
+6
-6
skills/opentui/docs/reference/tree-sitter.mdx
+6
-6
skills/opentui/docs/reference/tree-sitter.mdx
···
6
6
7
7
# Tree-sitter
8
8
9
-
OpenTUI integrates Tree-sitter for fast, accurate syntax highlighting. You can register parsers globally or per client.
9
+
OpenTUI integrates Tree-sitter for fast, accurate syntax highlighting. register parsers globally or per client.
10
10
11
11
## Add parsers globally
12
12
···
64
64
}
65
65
```
66
66
67
-
`aliases` maps additional filetype ids to the same parser assets.
67
+
`aliases` maps additional filetype ids to same parser assets.
68
68
69
69
## Language injections
70
70
···
98
98
})
99
99
```
100
100
101
-
If `infoStringMap` has no match, the fence language label is used as the filetype id.
101
+
If `infoStringMap` has no match, fence language label is used as filetype id.
102
102
103
103
## Use local files
104
104
···
119
119
120
120
## Automated asset management
121
121
122
-
Use the `updateAssets` utility to download parsers and generate imports.
122
+
Use `updateAssets` utility to download parsers and generate imports.
123
123
124
124
### CLI usage
125
125
···
166
166
167
167
## Caching
168
168
169
-
Parser and query files are cached in the client `dataPath`. Set a custom cache directory:
169
+
Parser and query files are cached in client `dataPath`. Set custom cache directory:
170
170
171
171
```typescript
172
172
const client = new TreeSitterClient({
···
186
186
187
187
`infoStringToFiletype()` is used for fenced markdown code blocks.
188
188
189
-
You can extend or override mappings at runtime:
189
+
extend or override mappings at runtime:
190
190
191
191
```typescript
192
192
import { extensionToFiletype, basenameToFiletype } from "@opentui/core"
+2
-2
skills/optimize/SKILL.md
+2
-2
skills/optimize/SKILL.md
···
1
1
---
2
2
name: optimize
3
-
description: "Diagnoses and fixes UI performance across loading speed, rendering, animations, images, and bundle size. Use when the user mentions slow, laggy, janky, performance, bundle size, load time, or wants a faster, smoother experience."
3
+
description: "Diagnoses and fixes UI performance across loading speed, rendering, animations, images, and bundle size. Use when user mentions slow, laggy, janky, performance, bundle size, load time, or wants faster, smoother experience."
4
4
argument-hint: "[target]"
5
5
user-invocable: true
6
6
---
···
262
262
- **No regressions**: Ensure functionality still works
263
263
- **User perception**: Does it feel faster?
264
264
265
-
Remember: Performance is a feature. Fast experiences feel more responsive, more polished, more professional. Optimize systematically, measure ruthlessly, and prioritize user-perceived performance.
265
+
Remember: Performance is feature. Fast experiences feel more responsive, more polished, more professional. Optimize systematically, measure ruthlessly, and prioritize user-perceived performance.
-265
skills/optimize/SKILL.md.original.md
-265
skills/optimize/SKILL.md.original.md
···
1
-
---
2
-
name: optimize
3
-
description: "Diagnoses and fixes UI performance across loading speed, rendering, animations, images, and bundle size. Use when the user mentions slow, laggy, janky, performance, bundle size, load time, or wants a faster, smoother experience."
4
-
argument-hint: "[target]"
5
-
user-invocable: true
6
-
---
7
-
8
-
Identify and fix performance issues to create faster, smoother user experiences.
9
-
10
-
## Assess Performance Issues
11
-
12
-
Understand current performance and identify problems.
13
-
14
-
### 1. Measure current state
15
-
- **Core Web Vitals**: LCP, FID/INP, CLS scores
16
-
- **Load time**: Time to interactive, first contentful paint
17
-
- **Bundle size**: JavaScript, CSS, image sizes
18
-
- **Runtime performance**: Frame rate, memory usage, CPU usage
19
-
- **Network**: Request count, payload sizes, waterfall
20
-
21
-
### 2. Identify bottlenecks
22
-
- What is slow? (Initial load? Interactions? Animations?)
23
-
- What is causing it? (Large images? Expensive JavaScript? Layout thrashing?)
24
-
- How bad is it? (Perceivable? Annoying? Blocking?)
25
-
- Who is affected? (All users? Mobile only? Slow connections?)
26
-
27
-
**CRITICAL**: Measure before and after. Premature optimization wastes time. Optimize what actually matters.
28
-
29
-
## Optimization Strategy
30
-
31
-
Create systematic improvement plan.
32
-
33
-
### Loading Performance
34
-
35
-
**Optimize Images**:
36
-
- Use modern formats (WebP, AVIF)
37
-
- Proper sizing (do not load 3000px image for 300px display)
38
-
- Lazy loading for below-fold images
39
-
- Responsive images (srcset, picture element)
40
-
- Compress images (80-85% quality is usually imperceptible)
41
-
- Use CDN for faster delivery
42
-
43
-
```html
44
-
<img
45
-
src="hero.webp"
46
-
srcset="hero-400.webp 400w, hero-800.webp 800w, hero-1200.webp 1200w"
47
-
sizes="(max-width: 400px) 400px, (max-width: 800px) 800px, 1200px"
48
-
loading="lazy"
49
-
alt="Hero image"
50
-
/>
51
-
```
52
-
53
-
**Reduce JavaScript Bundle**:
54
-
- Code splitting (route-based, component-based)
55
-
- Tree shaking (remove unused code)
56
-
- Remove unused dependencies
57
-
- Lazy load non-critical code
58
-
- Use dynamic imports for large components
59
-
60
-
```javascript
61
-
// Lazy load heavy component
62
-
const HeavyChart = lazy(() => import('./HeavyChart'));
63
-
```
64
-
65
-
**Optimize CSS**:
66
-
- Remove unused CSS
67
-
- Critical CSS inline, rest async
68
-
- Minimize CSS files
69
-
- Use CSS containment for independent regions
70
-
71
-
**Optimize Fonts**:
72
-
- Use font-display: swap or optional
73
-
- Subset fonts (only characters you need)
74
-
- Preload critical fonts
75
-
- Use system fonts when appropriate
76
-
- Limit font weights loaded
77
-
78
-
```css
79
-
@font-face {
80
-
font-family: 'CustomFont';
81
-
src: url('/fonts/custom.woff2') format('woff2');
82
-
font-display: swap; /* Show fallback immediately */
83
-
unicode-range: U+0020-007F; /* Basic Latin only */
84
-
}
85
-
```
86
-
87
-
**Optimize Loading Strategy**:
88
-
- Critical resources first (async or defer non-critical)
89
-
- Preload critical assets
90
-
- Prefetch likely next pages
91
-
- Service worker for offline or caching
92
-
- HTTP/2 or HTTP/3 for multiplexing
93
-
94
-
### Rendering Performance
95
-
96
-
**Avoid Layout Thrashing**:
97
-
```javascript
98
-
// Bad: Alternating reads and writes (causes reflows)
99
-
elements.forEach(el => {
100
-
const height = el.offsetHeight; // Read (forces layout)
101
-
el.style.height = height * 2; // Write
102
-
});
103
-
104
-
// Good: Batch reads, then batch writes
105
-
const heights = elements.map(el => el.offsetHeight); // All reads
106
-
elements.forEach((el, i) => {
107
-
el.style.height = heights[i] * 2; // All writes
108
-
});
109
-
```
110
-
111
-
**Optimize Rendering**:
112
-
- Use CSS contain property for independent regions
113
-
- Minimize DOM depth (flatter is faster)
114
-
- Reduce DOM size (fewer elements)
115
-
- Use content-visibility: auto for long lists
116
-
- Virtual scrolling for very long lists (react-window, react-virtualized)
117
-
118
-
**Reduce Paint and Composite**:
119
-
- Use transform and opacity for animations (GPU-accelerated)
120
-
- Avoid animating layout properties (width, height, top, left)
121
-
- Use will-change sparingly for known expensive operations
122
-
- Minimize paint areas (smaller is faster)
123
-
124
-
### Animation Performance
125
-
126
-
**GPU Acceleration**:
127
-
```css
128
-
/* Good: GPU-accelerated (fast) */
129
-
.animated {
130
-
transform: translateX(100px);
131
-
opacity: 0.5;
132
-
}
133
-
134
-
/* Bad: CPU-bound (slow) */
135
-
.animated {
136
-
left: 100px;
137
-
width: 300px;
138
-
}
139
-
```
140
-
141
-
**Smooth 60fps**:
142
-
- Target 16ms per frame (60fps)
143
-
- Use requestAnimationFrame for JS animations
144
-
- Debounce or throttle scroll handlers
145
-
- Use CSS animations when possible
146
-
- Avoid long-running JavaScript during animations
147
-
148
-
**Intersection Observer**:
149
-
```javascript
150
-
// Efficiently detect when elements enter viewport
151
-
const observer = new IntersectionObserver((entries) => {
152
-
entries.forEach(entry => {
153
-
if (entry.isIntersecting) {
154
-
// Element is visible, lazy load or animate
155
-
}
156
-
});
157
-
});
158
-
```
159
-
160
-
### React or Framework Optimization
161
-
162
-
**React-specific**:
163
-
- Use memo() for expensive components
164
-
- useMemo() and useCallback() for expensive computations
165
-
- Virtualize long lists
166
-
- Code split routes
167
-
- Avoid inline function creation in render
168
-
- Use React DevTools Profiler
169
-
170
-
**Framework-agnostic**:
171
-
- Minimize re-renders
172
-
- Debounce expensive operations
173
-
- Memoize computed values
174
-
- Lazy load routes and components
175
-
176
-
### Network Optimization
177
-
178
-
**Reduce Requests**:
179
-
- Combine small files
180
-
- Use SVG sprites for icons
181
-
- Inline small critical assets
182
-
- Remove unused third-party scripts
183
-
184
-
**Optimize APIs**:
185
-
- Use pagination (do not load everything)
186
-
- GraphQL to request only needed fields
187
-
- Response compression (gzip, brotli)
188
-
- HTTP caching headers
189
-
- CDN for static assets
190
-
191
-
**Optimize for Slow Connections**:
192
-
- Adaptive loading based on connection (navigator.connection)
193
-
- Optimistic UI updates
194
-
- Request prioritization
195
-
- Progressive enhancement
196
-
197
-
## Core Web Vitals Optimization
198
-
199
-
### Largest Contentful Paint (LCP < 2.5s)
200
-
- Optimize hero images
201
-
- Inline critical CSS
202
-
- Preload key resources
203
-
- Use CDN
204
-
- Server-side rendering
205
-
206
-
### First Input Delay (FID < 100ms) or INP (< 200ms)
207
-
- Break up long tasks
208
-
- Defer non-critical JavaScript
209
-
- Use web workers for heavy computation
210
-
- Reduce JavaScript execution time
211
-
212
-
### Cumulative Layout Shift (CLS < 0.1)
213
-
- Set dimensions on images and videos
214
-
- Do not inject content above existing content
215
-
- Use aspect-ratio CSS property
216
-
- Reserve space for ads and embeds
217
-
- Avoid animations that cause layout shifts
218
-
219
-
```css
220
-
/* Reserve space for image */
221
-
.image-container {
222
-
aspect-ratio: 16 / 9;
223
-
}
224
-
```
225
-
226
-
## Performance Monitoring
227
-
228
-
**Tools to use**:
229
-
- Chrome DevTools (Lighthouse, Performance panel)
230
-
- WebPageTest
231
-
- Core Web Vitals (Chrome UX Report)
232
-
- Bundle analyzers (webpack-bundle-analyzer)
233
-
- Performance monitoring (Sentry, DataDog, New Relic)
234
-
235
-
**Key metrics**:
236
-
- LCP, FID/INP, CLS (Core Web Vitals)
237
-
- Time to Interactive (TTI)
238
-
- First Contentful Paint (FCP)
239
-
- Total Blocking Time (TBT)
240
-
- Bundle size
241
-
- Request count
242
-
243
-
**IMPORTANT**: Measure on real devices with real network conditions. Desktop Chrome with fast connection is not representative.
244
-
245
-
**NEVER**:
246
-
- Optimize without measuring (premature optimization)
247
-
- Sacrifice accessibility for performance
248
-
- Break functionality while optimizing
249
-
- Use will-change everywhere (creates new layers, uses memory)
250
-
- Lazy load above-fold content
251
-
- Optimize micro-optimizations while ignoring major issues (optimize the biggest bottleneck first)
252
-
- Forget about mobile performance (often slower devices, slower connections)
253
-
254
-
## Verify Improvements
255
-
256
-
Test that optimizations worked.
257
-
258
-
- **Before and after metrics**: Compare Lighthouse scores
259
-
- **Real user monitoring**: Track improvements for real users
260
-
- **Different devices**: Test on low-end Android, not just flagship iPhone
261
-
- **Slow connections**: Throttle to 3G, test experience
262
-
- **No regressions**: Ensure functionality still works
263
-
- **User perception**: Does it feel faster?
264
-
265
-
Remember: Performance is a feature. Fast experiences feel more responsive, more polished, more professional. Optimize systematically, measure ruthlessly, and prioritize user-perceived performance.
+19
-19
skills/overdrive/SKILL.md
+19
-19
skills/overdrive/SKILL.md
···
1
1
---
2
2
name: overdrive
3
-
description: "Pushes interfaces past conventional limits with technically ambitious implementations — shaders, spring physics, scroll-driven reveals, 60fps animations. Use when the user wants to wow, impress, go all-out, or make something that feels extraordinary."
3
+
description: "Pushes interfaces past conventional limits with technically ambitious implementations — shaders, spring physics, scroll-driven reveals, 60fps animations. Use when user wants to wow, impress, go all-out, or make something that feels extraordinary."
4
4
argument-hint: "[target]"
5
5
user-invocable: true
6
6
---
···
12
12
》》》 Entering overdrive mode...
13
13
```
14
14
15
-
Push an interface past conventional limits. This is not about visual effects. It is about using the full power of the browser to make any part of an interface feel extraordinary: a table that handles a million rows, a dialog that morphs from its trigger, a form that validates in real-time with streaming feedback, a page transition that feels cinematic.
15
+
Push interface past conventional limits. This is not about visual effects. it's about using full power of browser to make any part of interface feel extraordinary: table that handles million rows, dialog that morphs from its trigger, form that validates in real-time with streaming feedback, page transition that feels cinematic.
16
16
17
17
## MANDATORY PREPARATION
18
18
19
-
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first.
19
+
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and Context Gathering Protocol. Follow protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first.
20
20
21
-
**EXTRA IMPORTANT FOR THIS SKILL**: Context determines what "extraordinary" means. A particle system on a creative portfolio is impressive. The same particle system on a settings page is embarrassing. But a settings page with instant optimistic saves and animated state transitions? That is extraordinary too. Understand the project personality and goals before deciding what is appropriate.
21
+
**EXTRA IMPORTANT FOR THIS SKILL**: Context determines what "extraordinary" means. particle system on creative portfolio is impressive. same particle system on settings page is embarrassing. But settings page with instant optimistic saves and animated state transitions? That is extraordinary too. Understand project personality and goals before deciding what is appropriate.
22
22
23
23
### Propose Before Building
24
24
25
-
This skill has the highest potential to misfire. Do NOT jump straight into implementation. You MUST:
25
+
This skill has highest potential to misfire. Do NOT jump straight into implementation. You MUST:
26
26
27
-
1. **Think through 2-3 different directions**. Consider different techniques, levels of ambition, and aesthetic approaches. For each direction, briefly describe what the result would look and feel like.
28
-
2. **{{ask_instruction}}** to present these directions and get the user pick before writing any code. Explain trade-offs (browser support, performance cost, complexity).
29
-
3. Only proceed with the direction the user confirms.
27
+
1. **Think through 2-3 different directions**. Consider different techniques, levels of ambition, and aesthetic approaches. For each direction, briefly describe what result would look and feel like.
28
+
2. **{{ask_instruction}}** to present these directions and get user pick before writing any code. Explain trade-offs (browser support, performance cost, complexity).
29
+
3. Only proceed with direction user confirms.
30
30
31
31
Skipping this step risks building something embarrassing that needs to be thrown away.
32
32
33
33
### Iterate with Browser Automation
34
34
35
-
Technically ambitious effects almost never work on the first try. You MUST actively use browser automation tools to preview your work, visually verify the result, and iterate. Do not assume the effect looks right. Check it. Expect multiple rounds of refinement. The gap between "technically works" and "looks extraordinary" is closed through visual iteration, not code alone.
35
+
Technically ambitious effects almost never work on first try. You MUST actively use browser automation tools to preview your work, visually verify result, and iterate. Do not assume effect looks right. Check it. Expect multiple rounds of refinement. gap between "technically works" and "looks extraordinary" is closed through visual iteration, not code alone.
36
36
37
37
---
38
38
39
39
## Assess What "Extraordinary" Means Here
40
40
41
-
The right kind of technical ambition depends entirely on what you are working with. Before choosing a technique, ask: **what would make a user of THIS specific interface say "wow, that is nice"?**
41
+
right kind of technical ambition depends entirely on what you are working with. Before choosing technique, ask: **what would make user of THIS specific interface say "wow, that is nice"?**
42
42
43
43
### For visual or marketing surfaces
44
-
Pages, hero sections, landing pages, portfolios. The "wow" is often sensory: a scroll-driven reveal, a shader background, a cinematic page transition, generative art that responds to the cursor.
44
+
Pages, hero sections, landing pages, portfolios. "wow" is often sensory: scroll-driven reveal, shader background, cinematic page transition, generative art that responds to cursor.
45
45
46
46
### For functional UI
47
-
Tables, forms, dialogs, navigation. The "wow" is in how it FEELS: a dialog that morphs from the button that triggered it via View Transitions, a data table that renders 100k rows at 60fps via virtual scrolling, a form with streaming validation that feels instant, drag-and-drop with spring physics.
47
+
Tables, forms, dialogs, navigation. "wow" is in how it FEELS: dialog that morphs from button that triggered it via View Transitions, data table that renders 100k rows at 60fps via virtual scrolling, form with streaming validation that feels instant, drag-and-drop with spring physics.
48
48
49
49
### For performance-critical UI
50
-
The "wow" is invisible but felt: a search that filters 50k items without a flicker, a complex form that never blocks the main thread, an image editor that processes in near-real-time. The interface never hesitates.
50
+
"wow" is invisible but felt: search that filters 50k items without flicker, complex form that never blocks main thread, image editor that processes in near-real-time. interface never hesitates.
51
51
52
52
### For data-heavy interfaces
53
-
Charts and dashboards. The "wow" is in fluidity: GPU-accelerated rendering via Canvas or WebGL for massive datasets, animated transitions between data states, force-directed graph layouts that settle naturally.
53
+
Charts and dashboards. "wow" is in fluidity: GPU-accelerated rendering via Canvas or WebGL for massive datasets, animated transitions between data states, force-directed graph layouts that settle naturally.
54
54
55
-
**The common thread**: something about the implementation goes beyond what users expect from a web interface. The technique serves the experience, not the other way around.
55
+
** common thread**: something about implementation goes beyond what users expect from web interface. technique serves experience, not other way around.
56
56
57
57
## The Toolkit
58
58
···
90
90
- **Web Audio API**. Spatial audio, audio-reactive visualizations, sonic feedback. Requires user gesture to start.
91
91
- **Device APIs**. Orientation, ambient light, geolocation. Use sparingly and always with user permission.
92
92
93
-
**NOTE**: This skill is about enhancing how an interface FEELS, not changing what a product DOES. Adding real-time collaboration, offline support, or new backend capabilities are product decisions, not UI enhancements. Focus on making existing features feel extraordinary.
93
+
**NOTE**: This skill is about enhancing how interface FEELS, not changing what product DOES. Adding real-time collaboration, offline support, or new backend capabilities are product decisions, not UI enhancements. Focus on making existing features feel extraordinary.
94
94
95
95
## Implement with Discipline
96
96
97
97
### Progressive enhancement is non-negotiable
98
98
99
-
Every technique must degrade gracefully. The experience without the enhancement must still be good.
99
+
Every technique must degrade gracefully. experience without enhancement must still be good.
100
100
101
101
```css
102
102
@supports (animation-timeline: scroll()) {
···
120
120
121
121
### Polish is the difference
122
122
123
-
The gap between "cool" and "extraordinary" is in the last 20% of refinement: the easing curve on a spring animation, the timing offset in a staggered reveal, the subtle secondary motion that makes a transition feel physical. Do not ship the first version that works. Ship the version that feels inevitable.
123
+
gap between "cool" and "extraordinary" is in last 20% of refinement: easing curve on spring animation, timing offset in staggered reveal, subtle secondary motion that makes transition feel physical. Do not ship first version that works. Ship version that feels inevitable.
124
124
125
125
**NEVER**:
126
126
- Ignore prefers-reduced-motion. This is accessibility requirement, not suggestion
···
138
138
- ** accessibility test**: Enable reduced motion. Still beautiful?
139
139
- ** context test**: Does this make sense for THIS brand and audience?
140
140
141
-
Remember: "Technically extraordinary" is not about using the newest API. It is about making an interface do something users did not think a website could do.
141
+
Remember: "Technically extraordinary" is not about using newest API. it's about making interface do something users did not think website could do.
-141
skills/overdrive/SKILL.md.original.md
-141
skills/overdrive/SKILL.md.original.md
···
1
-
---
2
-
name: overdrive
3
-
description: "Pushes interfaces past conventional limits with technically ambitious implementations — shaders, spring physics, scroll-driven reveals, 60fps animations. Use when the user wants to wow, impress, go all-out, or make something that feels extraordinary."
4
-
argument-hint: "[target]"
5
-
user-invocable: true
6
-
---
7
-
8
-
Start your response with:
9
-
10
-
```
11
-
───────────── ⚡ OVERDRIVE ─────────────
12
-
》》》 Entering overdrive mode...
13
-
```
14
-
15
-
Push an interface past conventional limits. This is not just about visual effects. It is about using the full power of the browser to make any part of an interface feel extraordinary: a table that handles a million rows, a dialog that morphs from its trigger, a form that validates in real-time with streaming feedback, a page transition that feels cinematic.
16
-
17
-
## MANDATORY PREPARATION
18
-
19
-
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first.
20
-
21
-
**EXTRA IMPORTANT FOR THIS SKILL**: Context determines what "extraordinary" means. A particle system on a creative portfolio is impressive. The same particle system on a settings page is embarrassing. But a settings page with instant optimistic saves and animated state transitions? That is extraordinary too. Understand the project personality and goals before deciding what is appropriate.
22
-
23
-
### Propose Before Building
24
-
25
-
This skill has the highest potential to misfire. Do NOT jump straight into implementation. You MUST:
26
-
27
-
1. **Think through 2-3 different directions**. Consider different techniques, levels of ambition, and aesthetic approaches. For each direction, briefly describe what the result would look and feel like.
28
-
2. **{{ask_instruction}}** to present these directions and get the user pick before writing any code. Explain trade-offs (browser support, performance cost, complexity).
29
-
3. Only proceed with the direction the user confirms.
30
-
31
-
Skipping this step risks building something embarrassing that needs to be thrown away.
32
-
33
-
### Iterate with Browser Automation
34
-
35
-
Technically ambitious effects almost never work on the first try. You MUST actively use browser automation tools to preview your work, visually verify the result, and iterate. Do not assume the effect looks right. Check it. Expect multiple rounds of refinement. The gap between "technically works" and "looks extraordinary" is closed through visual iteration, not code alone.
36
-
37
-
---
38
-
39
-
## Assess What "Extraordinary" Means Here
40
-
41
-
The right kind of technical ambition depends entirely on what you are working with. Before choosing a technique, ask: **what would make a user of THIS specific interface say "wow, that is nice"?**
42
-
43
-
### For visual or marketing surfaces
44
-
Pages, hero sections, landing pages, portfolios. The "wow" is often sensory: a scroll-driven reveal, a shader background, a cinematic page transition, generative art that responds to the cursor.
45
-
46
-
### For functional UI
47
-
Tables, forms, dialogs, navigation. The "wow" is in how it FEELS: a dialog that morphs from the button that triggered it via View Transitions, a data table that renders 100k rows at 60fps via virtual scrolling, a form with streaming validation that feels instant, drag-and-drop with spring physics.
48
-
49
-
### For performance-critical UI
50
-
The "wow" is invisible but felt: a search that filters 50k items without a flicker, a complex form that never blocks the main thread, an image editor that processes in near-real-time. The interface just never hesitates.
51
-
52
-
### For data-heavy interfaces
53
-
Charts and dashboards. The "wow" is in fluidity: GPU-accelerated rendering via Canvas or WebGL for massive datasets, animated transitions between data states, force-directed graph layouts that settle naturally.
54
-
55
-
**The common thread**: something about the implementation goes beyond what users expect from a web interface. The technique serves the experience, not the other way around.
56
-
57
-
## The Toolkit
58
-
59
-
Organized by what you are trying to achieve, not by technology name.
60
-
61
-
### Make transitions feel cinematic
62
-
- **View Transitions API** (same-document: all browsers; cross-document: no Firefox). Shared element morphing between states. A list item expanding into a detail page. A button morphing into a dialog. This is the closest thing to native FLIP animations.
63
-
- **@starting-style** (all browsers). Animate elements from display: none to visible with CSS only, including entry keyframes.
64
-
- **Spring physics**. Natural motion with mass, tension, and damping instead of cubic-bezier. Libraries: motion (formerly Framer Motion), GSAP, or roll your own spring solver.
65
-
66
-
### Tie animation to scroll position
67
-
- **Scroll-driven animations** (animation-timeline: scroll()). CSS-only, no JS. Parallax, progress bars, reveal sequences all driven by scroll position. (Chrome, Edge, Safari; Firefox: flag only. Always provide a static fallback)
68
-
69
-
### Render beyond CSS
70
-
- **WebGL** (all browsers). Shader effects, post-processing, particle systems. Libraries: Three.js, OGL (lightweight), regl. Use for effects CSS cannot express.
71
-
- **WebGPU** (Chrome, Edge; Safari partial; Firefox: flag only). Next-gen GPU compute. More powerful than WebGL but limited browser support. Always fall back to WebGL2.
72
-
- **Canvas 2D or OffscreenCanvas**. Custom rendering, pixel manipulation, or moving heavy rendering off the main thread entirely via Web Workers and OffscreenCanvas.
73
-
- **SVG filter chains**. Displacement maps, turbulence, morphology for organic distortion effects. CSS-animatable.
74
-
75
-
### Make data feel alive
76
-
- **Virtual scrolling**. Render only visible rows for tables or lists with tens of thousands of items. No library required for simple cases. TanStack Virtual for complex ones.
77
-
- **GPU-accelerated charts**. Canvas or WebGL-rendered data visualization for datasets too large for SVG or DOM. Libraries: deck.gl, regl-based custom renderers.
78
-
- **Animated data transitions**. Morph between chart states rather than replacing. D3 transition() or View Transitions for DOM-based charts.
79
-
80
-
### Animate complex properties
81
-
- **@property** (all browsers). Register custom CSS properties with types, enabling animation of gradients, colors, and complex values that CSS cannot normally interpolate.
82
-
- **Web Animations API** (all browsers). JavaScript-driven animations with the performance of CSS. Composable, cancellable, reversible. The foundation for complex choreography.
83
-
84
-
### Push performance boundaries
85
-
- **Web Workers**. Move computation off the main thread. Heavy data processing, image manipulation, search indexing. Anything that would cause jank.
86
-
- **OffscreenCanvas**. Render in a Worker thread. The main thread stays free while complex visuals render in the background.
87
-
- **WASM**. Near-native performance for computation-heavy features. Image processing, physics simulations, codecs.
88
-
89
-
### Interact with the device
90
-
- **Web Audio API**. Spatial audio, audio-reactive visualizations, sonic feedback. Requires user gesture to start.
91
-
- **Device APIs**. Orientation, ambient light, geolocation. Use sparingly and always with user permission.
92
-
93
-
**NOTE**: This skill is about enhancing how an interface FEELS, not changing what a product DOES. Adding real-time collaboration, offline support, or new backend capabilities are product decisions, not UI enhancements. Focus on making existing features feel extraordinary.
94
-
95
-
## Implement with Discipline
96
-
97
-
### Progressive enhancement is non-negotiable
98
-
99
-
Every technique must degrade gracefully. The experience without the enhancement must still be good.
100
-
101
-
```css
102
-
@supports (animation-timeline: scroll()) {
103
-
.hero { animation-timeline: scroll(); }
104
-
}
105
-
```
106
-
107
-
```javascript
108
-
if ('gpu' in navigator) { /* WebGPU */ }
109
-
else if (canvas.getContext('webgl2')) { /* WebGL2 fallback */ }
110
-
/* CSS-only fallback must still look good */
111
-
```
112
-
113
-
### Performance rules
114
-
115
-
- Target 60fps. If dropping below 50, simplify.
116
-
- Respect prefers-reduced-motion. Always. Provide a beautiful static alternative.
117
-
- Lazy-initialize heavy resources (WebGL contexts, WASM modules) only when near viewport.
118
-
- Pause off-screen rendering. Kill what you cannot see.
119
-
- Test on real mid-range devices, not just your development machine.
120
-
121
-
### Polish is the difference
122
-
123
-
The gap between "cool" and "extraordinary" is in the last 20% of refinement: the easing curve on a spring animation, the timing offset in a staggered reveal, the subtle secondary motion that makes a transition feel physical. Do not ship the first version that works. Ship the version that feels inevitable.
124
-
125
-
**NEVER**:
126
-
- Ignore prefers-reduced-motion. This is an accessibility requirement, not a suggestion
127
-
- Ship effects that cause jank on mid-range devices
128
-
- Use bleeding-edge APIs without a functional fallback
129
-
- Add sound without explicit user opt-in
130
-
- Use technical ambition to mask weak design fundamentals. Fix those first with other skills.
131
-
- Layer multiple competing extraordinary moments. Focus creates impact, excess creates noise.
132
-
133
-
## Verify the Result
134
-
135
-
- **The wow test**: Show it to someone who has not seen it. Do they react?
136
-
- **The removal test**: Take it away. Does the experience feel diminished, or does nobody notice?
137
-
- **The device test**: Run it on a phone, a tablet, a Chromebook. Still smooth?
138
-
- **The accessibility test**: Enable reduced motion. Still beautiful?
139
-
- **The context test**: Does this make sense for THIS brand and audience?
140
-
141
-
Remember: "Technically extraordinary" is not about using the newest API. It is about making an interface do something users did not think a website could do.
+8
-8
skills/polish/SKILL.md
+8
-8
skills/polish/SKILL.md
···
1
1
---
2
2
name: polish
3
-
description: "Performs a final quality pass fixing alignment, spacing, consistency, and micro-detail issues before shipping. Use when the user mentions polish, finishing touches, pre-launch review, something looks off, or wants to go from good to great."
3
+
description: "Performs final quality pass fixing alignment, spacing, consistency, and micro-detail issues before shipping. Use when user mentions polish, finishing touches, pre-launch review, something looks off, or wants to go from good to great."
4
4
argument-hint: "[target]"
5
5
user-invocable: true
6
6
---
7
7
8
8
## MANDATORY PREPARATION
9
9
10
-
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. gather: quality bar (MVP vs flagship).
10
+
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and Context Gathering Protocol. Follow protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. gather: quality bar (MVP vs flagship).
11
11
12
12
---
13
13
14
-
Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished.
14
+
Perform meticulous final pass to catch all small details that separate good work from great work. difference between shipped and polished.
15
15
16
16
## Pre-Polish Assessment
17
17
18
-
Understand the current state and goals.
18
+
Understand current state and goals.
19
19
20
20
### 1. Review completeness
21
21
- Is it functionally complete?
···
31
31
- Edge cases and error states
32
32
- Loading and transition smoothness
33
33
34
-
**CRITICAL**: Polish is the last step, not the first. Do not polish work that is not functionally complete.
34
+
**CRITICAL**: Polish is last step, not first. Do not polish work that is not functionally complete.
35
35
36
36
## Polish Systematically
37
37
···
169
169
- [ ] Respects reduced motion preference
170
170
- [ ] Code is clean (no TODOs, console.logs, commented code)
171
171
172
-
**IMPORTANT**: Polish is about details. Zoom in. Squint at it. Use it yourself. The little things add up.
172
+
**IMPORTANT**: Polish is about details. Zoom in. Squint at it. Use it yourself. little things add up.
173
173
174
174
**NEVER**:
175
-
- Polish before it is functionally complete
175
+
- Polish before it's functionally complete
176
176
- Spend hours on polish if it ships in 30 minutes (triage)
177
177
- Introduce bugs while polishing (test thoroughly)
178
178
- Ignore systematic issues (if spacing is off everywhere, fix system)
···
188
188
- **Compare to design**: Match intended design
189
189
- **Check all states**: Do not test happy path
190
190
191
-
Remember: You have impeccable attention to detail and exquisite taste. Polish until it feels effortless, looks intentional, and works flawlessly. Sweat the details. They matter.
191
+
Remember: You have impeccable attention to detail and exquisite taste. Polish until it feels effortless, looks intentional, and works flawlessly. Sweat details. They matter.
-191
skills/polish/SKILL.md.original.md
-191
skills/polish/SKILL.md.original.md
···
1
-
---
2
-
name: polish
3
-
description: "Performs a final quality pass fixing alignment, spacing, consistency, and micro-detail issues before shipping. Use when the user mentions polish, finishing touches, pre-launch review, something looks off, or wants to go from good to great."
4
-
argument-hint: "[target]"
5
-
user-invocable: true
6
-
---
7
-
8
-
## MANDATORY PREPARATION
9
-
10
-
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first. Additionally gather: quality bar (MVP vs flagship).
11
-
12
-
---
13
-
14
-
Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished.
15
-
16
-
## Pre-Polish Assessment
17
-
18
-
Understand the current state and goals.
19
-
20
-
### 1. Review completeness
21
-
- Is it functionally complete?
22
-
- Are there known issues to preserve (mark with TODOs)?
23
-
- What is the quality bar? (MVP vs flagship feature?)
24
-
- When does it ship? (How much time for polish?)
25
-
26
-
### 2. Identify polish areas
27
-
- Visual inconsistencies
28
-
- Spacing and alignment issues
29
-
- Interaction state gaps
30
-
- Copy inconsistencies
31
-
- Edge cases and error states
32
-
- Loading and transition smoothness
33
-
34
-
**CRITICAL**: Polish is the last step, not the first. Do not polish work that is not functionally complete.
35
-
36
-
## Polish Systematically
37
-
38
-
Work through these dimensions methodically.
39
-
40
-
### Visual Alignment and Spacing
41
-
- **Pixel-perfect alignment**: Everything lines up to grid
42
-
- **Consistent spacing**: All gaps use spacing scale (no random 13px gaps)
43
-
- **Optical alignment**: Adjust for visual weight (icons may need offset for optical centering)
44
-
- **Responsive consistency**: Spacing and alignment work at all breakpoints
45
-
- **Grid adherence**: Elements snap to baseline grid
46
-
47
-
**Check**:
48
-
- Enable grid overlay and verify alignment
49
-
- Check spacing with browser inspector
50
-
- Test at multiple viewport sizes
51
-
- Look for elements that "feel" off
52
-
53
-
### Typography Refinement
54
-
- **Hierarchy consistency**: Same elements use same sizes and weights throughout
55
-
- **Line length**: 45-75 characters for body text
56
-
- **Line height**: Appropriate for font size and context
57
-
- **Widows and orphans**: No single words on last line
58
-
- **Hyphenation**: Appropriate for language and column width
59
-
- **Kerning**: Adjust letter spacing where needed (especially headlines)
60
-
- **Font loading**: No FOUT or FOIT flashes
61
-
62
-
### Color and Contrast
63
-
- **Contrast ratios**: All text meets WCAG standards
64
-
- **Consistent token usage**: No hard-coded colors, all use design tokens
65
-
- **Theme consistency**: Works in all theme variants
66
-
- **Color meaning**: Same colors mean same things throughout
67
-
- **Accessible focus**: Focus indicators visible with sufficient contrast
68
-
- **Tinted neutrals**: No pure gray or pure black. Add subtle color tint (0.01 chroma).
69
-
- **Gray on color**: Never put gray text on colored backgrounds. Use a shade of that color or transparency.
70
-
71
-
### Interaction States
72
-
73
-
Every interactive element needs all states.
74
-
75
-
- **Default**: Resting state
76
-
- **Hover**: Subtle feedback (color, scale, shadow)
77
-
- **Focus**: Keyboard focus indicator (never remove without replacement)
78
-
- **Active**: Click or tap feedback
79
-
- **Disabled**: Clearly non-interactive
80
-
- **Loading**: Async action feedback
81
-
- **Error**: Validation or error state
82
-
- **Success**: Successful completion
83
-
84
-
**Missing states create confusion and broken experiences**.
85
-
86
-
### Micro-interactions and Transitions
87
-
- **Smooth transitions**: All state changes animated appropriately (150-300ms)
88
-
- **Consistent easing**: Use ease-out-quart, quint, or expo for natural deceleration. Never bounce or elastic. They feel dated.
89
-
- **No jank**: 60fps animations, only animate transform and opacity
90
-
- **Appropriate motion**: Motion serves purpose, not decoration
91
-
- **Reduced motion**: Respects prefers-reduced-motion
92
-
93
-
### Content and Copy
94
-
- **Consistent terminology**: Same things called same names throughout
95
-
- **Consistent capitalization**: Title Case vs Sentence case applied consistently
96
-
- **Grammar and spelling**: No typos
97
-
- **Appropriate length**: Not too wordy, not too terse
98
-
- **Punctuation consistency**: Periods on sentences, not on labels (unless all labels have them)
99
-
100
-
### Icons and Images
101
-
- **Consistent style**: All icons from same family or matching style
102
-
- **Appropriate sizing**: Icons sized consistently for context
103
-
- **Proper alignment**: Icons align with adjacent text optically
104
-
- **Alt text**: All images have descriptive alt text
105
-
- **Loading states**: Images do not cause layout shift, proper aspect ratios
106
-
- **Retina support**: 2x assets for high-DPI screens
107
-
108
-
### Forms and Inputs
109
-
- **Label consistency**: All inputs properly labeled
110
-
- **Required indicators**: Clear and consistent
111
-
- **Error messages**: Helpful and consistent
112
-
- **Tab order**: Logical keyboard navigation
113
-
- **Auto-focus**: Appropriate (do not overuse)
114
-
- **Validation timing**: Consistent (on blur vs on submit)
115
-
116
-
### Edge Cases and Error States
117
-
- **Loading states**: All async actions have loading feedback
118
-
- **Empty states**: Helpful empty states, not just blank space
119
-
- **Error states**: Clear error messages with recovery paths
120
-
- **Success states**: Confirmation of successful actions
121
-
- **Long content**: Handles very long names, descriptions, and so on
122
-
- **No content**: Handles missing data gracefully
123
-
- **Offline**: Appropriate offline handling (if applicable)
124
-
125
-
### Responsiveness
126
-
- **All breakpoints**: Test mobile, tablet, desktop
127
-
- **Touch targets**: 44x44px minimum on touch devices
128
-
- **Readable text**: No text smaller than 14px on mobile
129
-
- **No horizontal scroll**: Content fits viewport
130
-
- **Appropriate reflow**: Content adapts logically
131
-
132
-
### Performance
133
-
- **Fast initial load**: Optimize critical path
134
-
- **No layout shift**: Elements do not jump after load (CLS)
135
-
- **Smooth interactions**: No lag or jank
136
-
- **Optimized images**: Appropriate formats and sizes
137
-
- **Lazy loading**: Off-screen content loads lazily
138
-
139
-
### Code Quality
140
-
- **Remove console logs**: No debug logging in production
141
-
- **Remove commented code**: Clean up dead code
142
-
- **Remove unused imports**: Clean up unused dependencies
143
-
- **Consistent naming**: Variables and functions follow conventions
144
-
- **Type safety**: No TypeScript any or ignored errors
145
-
- **Accessibility**: Proper ARIA labels and semantic HTML
146
-
147
-
## Polish Checklist
148
-
149
-
Go through systematically.
150
-
151
-
- [ ] Visual alignment perfect at all breakpoints
152
-
- [ ] Spacing uses design tokens consistently
153
-
- [ ] Typography hierarchy consistent
154
-
- [ ] All interactive states implemented
155
-
- [ ] All transitions smooth (60fps)
156
-
- [ ] Copy is consistent and polished
157
-
- [ ] Icons are consistent and properly sized
158
-
- [ ] All forms properly labeled and validated
159
-
- [ ] Error states are helpful
160
-
- [ ] Loading states are clear
161
-
- [ ] Empty states are welcoming
162
-
- [ ] Touch targets are 44x44px minimum
163
-
- [ ] Contrast ratios meet WCAG AA
164
-
- [ ] Keyboard navigation works
165
-
- [ ] Focus indicators visible
166
-
- [ ] No console errors or warnings
167
-
- [ ] No layout shift on load
168
-
- [ ] Works in all supported browsers
169
-
- [ ] Respects reduced motion preference
170
-
- [ ] Code is clean (no TODOs, console.logs, commented code)
171
-
172
-
**IMPORTANT**: Polish is about details. Zoom in. Squint at it. Use it yourself. The little things add up.
173
-
174
-
**NEVER**:
175
-
- Polish before it is functionally complete
176
-
- Spend hours on polish if it ships in 30 minutes (triage)
177
-
- Introduce bugs while polishing (test thoroughly)
178
-
- Ignore systematic issues (if spacing is off everywhere, fix the system)
179
-
- Perfect one thing while leaving others rough (consistent quality level)
180
-
181
-
## Final Verification
182
-
183
-
Before marking as done.
184
-
185
-
- **Use it yourself**: Actually interact with the feature
186
-
- **Test on real devices**: Not just browser DevTools
187
-
- **Ask someone else to review**: Fresh eyes catch things
188
-
- **Compare to design**: Match intended design
189
-
- **Check all states**: Do not just test happy path
190
-
191
-
Remember: You have impeccable attention to detail and exquisite taste. Polish until it feels effortless, looks intentional, and works flawlessly. Sweat the details. They matter.
+7
-7
skills/quieter/SKILL.md
+7
-7
skills/quieter/SKILL.md
···
1
1
---
2
2
name: quieter
3
-
description: "Tones down visually aggressive or overstimulating designs, reducing intensity while preserving quality. Use when the user mentions too bold, too loud, overwhelming, aggressive, garish, or wants a calmer, more refined aesthetic."
3
+
description: "Tones down visually aggressive or overstimulating designs, reducing intensity while preserving quality. Use when user mentions too bold, too loud, overwhelming, aggressive, garish, or wants calmer, more refined aesthetic."
4
4
argument-hint: "[target]"
5
5
user-invocable: true
6
6
---
7
7
8
-
Reduce visual intensity in designs that are too bold, aggressive, or overstimulating, creating a more refined and approachable aesthetic without losing effectiveness.
8
+
Reduce visual intensity in designs that are too bold, aggressive, or overstimulating, creating more refined and approachable aesthetic without losing effectiveness.
9
9
10
10
## MANDATORY PREPARATION
11
11
12
-
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first.
12
+
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and Context Gathering Protocol. Follow protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first.
13
13
14
14
---
15
15
16
16
## Assess Current State
17
17
18
-
Analyze what makes the design feel too intense.
18
+
Analyze what makes design feel too intense.
19
19
20
20
### 1. Identify intensity sources
21
21
- **Color saturation**: Overly bright or saturated colors
···
31
31
- What is working? (Do not throw away good ideas)
32
32
- What is core message? (Preserve what matters)
33
33
34
-
If any of these are unclear from the codebase, {{ask_instruction}}
34
+
If any of these are unclear from codebase, {{ask_instruction}}
35
35
36
-
**CRITICAL**: "Quieter" does not mean boring or generic. It means refined, sophisticated, and easier on the eyes. Think luxury, not laziness.
36
+
**CRITICAL**: "Quieter" does not mean boring or generic. It means refined, sophisticated, and easier on eyes. Think luxury, not laziness.
37
37
38
38
## Plan Refinement
39
39
40
-
Create a strategy to reduce intensity while maintaining impact.
40
+
Create strategy to reduce intensity while maintaining impact.
41
41
42
42
- **Color approach**: Desaturate or shift to more sophisticated tones?
43
43
- **Hierarchy approach**: Which elements should stay bold (very few), which should recede?
-102
skills/quieter/SKILL.md.original.md
-102
skills/quieter/SKILL.md.original.md
···
1
-
---
2
-
name: quieter
3
-
description: "Tones down visually aggressive or overstimulating designs, reducing intensity while preserving quality. Use when the user mentions too bold, too loud, overwhelming, aggressive, garish, or wants a calmer, more refined aesthetic."
4
-
argument-hint: "[target]"
5
-
user-invocable: true
6
-
---
7
-
8
-
Reduce visual intensity in designs that are too bold, aggressive, or overstimulating, creating a more refined and approachable aesthetic without losing effectiveness.
9
-
10
-
## MANDATORY PREPARATION
11
-
12
-
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first.
13
-
14
-
---
15
-
16
-
## Assess Current State
17
-
18
-
Analyze what makes the design feel too intense.
19
-
20
-
### 1. Identify intensity sources
21
-
- **Color saturation**: Overly bright or saturated colors
22
-
- **Contrast extremes**: Too much high-contrast juxtaposition
23
-
- **Visual weight**: Too many bold, heavy elements competing
24
-
- **Animation excess**: Too much motion or overly dramatic effects
25
-
- **Complexity**: Too many visual elements, patterns, or decorations
26
-
- **Scale**: Everything is large and loud with no hierarchy
27
-
28
-
### 2. Understand the context
29
-
- What is the purpose? (Marketing vs tool vs reading experience)
30
-
- Who is the audience? (Some contexts need energy)
31
-
- What is working? (Do not throw away good ideas)
32
-
- What is the core message? (Preserve what matters)
33
-
34
-
If any of these are unclear from the codebase, {{ask_instruction}}
35
-
36
-
**CRITICAL**: "Quieter" does not mean boring or generic. It means refined, sophisticated, and easier on the eyes. Think luxury, not laziness.
37
-
38
-
## Plan Refinement
39
-
40
-
Create a strategy to reduce intensity while maintaining impact.
41
-
42
-
- **Color approach**: Desaturate or shift to more sophisticated tones?
43
-
- **Hierarchy approach**: Which elements should stay bold (very few), which should recede?
44
-
- **Simplification approach**: What can be removed entirely?
45
-
- **Sophistication approach**: How can we signal quality through restraint?
46
-
47
-
**IMPORTANT**: Great quiet design is harder than great bold design. Subtlety requires precision.
48
-
49
-
## Refine the Design
50
-
51
-
Systematically reduce intensity across these dimensions.
52
-
53
-
### Color Refinement
54
-
- **Reduce saturation**: Shift from fully saturated to 70-85% saturation
55
-
- **Soften palette**: Replace bright colors with muted, sophisticated tones
56
-
- **Reduce color variety**: Use fewer colors more thoughtfully
57
-
- **Neutral dominance**: Let neutrals do more work, use color as accent (10% rule)
58
-
- **Gentler contrasts**: High contrast only where it matters most
59
-
- **Tinted grays**: Use warm or cool tinted grays instead of pure gray. Adds sophistication without loudness.
60
-
- **Never gray on color**: If you have gray text on a colored background, use a darker shade of that color or transparency instead.
61
-
62
-
### Visual Weight Reduction
63
-
- **Typography**: Reduce font weights (900 to 600, 700 to 500), decrease sizes where appropriate
64
-
- **Hierarchy through subtlety**: Use weight, size, and space instead of color and boldness
65
-
- **White space**: Increase breathing room, reduce density
66
-
- **Borders and lines**: Reduce thickness, decrease opacity, or remove entirely
67
-
68
-
### Simplification
69
-
- **Remove decorative elements**: Gradients, shadows, patterns, textures that do not serve purpose
70
-
- **Simplify shapes**: Reduce border radius extremes, simplify custom shapes
71
-
- **Reduce layering**: Flatten visual hierarchy where possible
72
-
- **Clean up effects**: Reduce or remove blur effects, glows, multiple shadows
73
-
74
-
### Motion Reduction
75
-
- **Reduce animation intensity**: Shorter distances (10-20px instead of 40px), gentler easing
76
-
- **Remove decorative animations**: Keep functional motion, remove flourishes
77
-
- **Subtle micro-interactions**: Replace dramatic effects with gentle feedback
78
-
- **Refined easing**: Use ease-out-quart for smooth, understated motion. Never bounce or elastic.
79
-
- **Remove animations entirely** if they are not serving a clear purpose.
80
-
81
-
### Composition Refinement
82
-
- **Reduce scale jumps**: Smaller contrast between sizes creates calmer feeling
83
-
- **Align to grid**: Bring rogue elements back into systematic alignment
84
-
- **Even out spacing**: Replace extreme spacing variations with consistent rhythm
85
-
86
-
**NEVER**:
87
-
- Make everything the same size or weight (hierarchy still matters)
88
-
- Remove all color (quiet equals grayscale)
89
-
- Eliminate all personality (maintain character through refinement)
90
-
- Sacrifice usability for aesthetics (functional elements still need clear affordances)
91
-
- Make everything small and light (some anchors needed)
92
-
93
-
## Verify Quality
94
-
95
-
Ensure refinement maintains quality.
96
-
97
-
- **Still functional**: Can users still accomplish tasks easily?
98
-
- **Still distinctive**: Does it have character, or is it generic now?
99
-
- **Better reading**: Is text easier to read for extended periods?
100
-
- **Sophistication**: Does it feel more refined and premium?
101
-
102
-
Remember: Quiet design is confident design. It does not need to shout. Less is more, but less is also harder. Refine with precision and maintain intentionality.
+34
-34
skills/shadcn/SKILL.md
+34
-34
skills/shadcn/SKILL.md
···
7
7
8
8
# shadcn/ui
9
9
10
-
A UI framework for components and design systems. The CLI adds source code to the user's project.
10
+
UI framework for components and design systems. CLI adds source code to user's project.
11
11
12
-
> **IMPORTANT:** Run CLI commands with the project's package runner: `npx shadcn@latest`, `pnpm dlx shadcn@latest`, or `bunx --bun shadcn@latest`, based on `packageManager`. Examples use `npx shadcn@latest`; swap to the project runner.
12
+
> **IMPORTANT:** Run CLI commands with project's package runner: `npx shadcn@latest`, `pnpm dlx shadcn@latest`, or `bunx --bun shadcn@latest`, based on `packageManager`. Examples use `npx shadcn@latest`; swap to project runner.
13
13
14
14
## Current Project Context
15
15
···
17
17
!`npx shadcn@latest info --json`
18
18
```
19
19
20
-
Use the JSON for project config and installed components. Run `npx shadcn@latest docs <component>` for docs and example URLs.
20
+
Use JSON for project config and installed components. Run `npx shadcn@latest docs <component>` for docs and example URLs.
21
21
22
22
## Principles
23
23
···
46
46
- `InputGroup` uses `InputGroupInput` and `InputGroupTextarea`. Do not place raw `Input` or `Textarea` inside `InputGroup`.
47
47
- Buttons inside inputs use `InputGroup` + `InputGroupAddon`.
48
48
- Option sets with 2 to 7 choices use `ToggleGroup`. Do not loop `Button` with manual active state.
49
-
- Use `FieldSet` + `FieldLegend` for related checkboxes and radios. Do not use a `div` with a heading.
50
-
- Validation uses `data-invalid` on `Field` and `aria-invalid` on the control. For disabled, use `data-disabled` on `Field` and `disabled` on the control.
49
+
- Use `FieldSet` + `FieldLegend` for related checkboxes and radios. Do not use `div` with heading.
50
+
- Validation uses `data-invalid` on `Field` and `aria-invalid` on control. For disabled, use `data-disabled` on `Field` and `disabled` on control.
51
51
52
52
### Component Structure → [composition.md](./rules/composition.md)
53
53
54
54
- Items stay inside their group. `SelectItem` → `SelectGroup`. `DropdownMenuItem` → `DropdownMenuGroup`. `CommandItem` → `CommandGroup`.
55
55
- Use `asChild` for radix or `render` for base when making custom triggers. Check `base` in `npx shadcn@latest info`. → [base-vs-radix.md](./rules/base-vs-radix.md)
56
-
- Dialog, Sheet, and Drawer need a Title. Use `DialogTitle`, `SheetTitle`, or `DrawerTitle`. Hide with `className="sr-only"` if needed.
56
+
- Dialog, Sheet, and Drawer need Title. Use `DialogTitle`, `SheetTitle`, or `DrawerTitle`. Hide with `className="sr-only"` if needed.
57
57
- Use full Card composition: `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`.
58
58
- Button has no `isPending` or `isLoading`. Compose with `Spinner` + `data-icon` + `disabled`.
59
59
- `TabsTrigger` must stay inside `TabsList`.
···
61
61
62
62
### Use Components, Not Custom Markup → [composition.md](./rules/composition.md)
63
63
64
-
- Use existing components before custom markup. Check if a component exists before writing a styled `div`.
64
+
- Use existing components before custom markup. Check if component exists before writing styled `div`.
65
65
- Callouts use `Alert`.
66
66
- Empty states use `Empty`.
67
67
- Toasts use `sonner` and `toast()`.
···
73
73
74
74
- Icons in `Button` use `data-icon`, either `inline-start` or `inline-end`.
75
75
- Do not size icons inside components. Components handle icon sizing. No `size-4` or `w-4 h-4`.
76
-
- Pass icons as objects, not string keys. `icon={CheckIcon}`, not a string lookup.
76
+
- Pass icons as objects, not string keys. `icon={CheckIcon}`, not string lookup.
77
77
78
78
### CLI
79
79
80
80
- Never decode preset codes or build preset URLs manually. Use `preset decode`, `preset url`, or `preset open`. For project-aware detection, use `preset resolve`.
81
-
- Apply preset codes directly with the CLI. Use `apply <code>` for existing projects, or `init --preset <code>` when initializing.
81
+
- Apply preset codes directly with CLI. Use `apply <code>` for existing projects, or `init --preset <code>` when initializing.
82
82
83
83
## Key Patterns
84
84
···
139
139
140
140
Injected project context fields:
141
141
142
-
- `aliases` means use the real alias prefix for imports, never hardcode.
142
+
- `aliases` means use real alias prefix for imports, never hardcode.
143
143
- `isRSC` means components with `useState`, `useEffect`, handlers, or browser APIs need `"use client"`.
144
144
- `tailwindVersion` means `v4` uses `@theme inline` and `v3` uses `tailwind.config.js`.
145
-
- `tailwindCssFile` is the global CSS file for custom CSS variables. Edit this file, never create a new one.
146
-
- `style` is the component visual treatment, like `nova` or `vega`.
147
-
- `base` is the primitive library, `radix` or `base`. It affects APIs and props.
145
+
- `tailwindCssFile` is global CSS file for custom CSS variables. Edit this file, never create new one.
146
+
- `style` is component visual treatment, like `nova` or `vega`.
147
+
- `base` is primitive library, `radix` or `base`. It affects APIs and props.
148
148
- `iconLibrary` controls icon imports. Use `lucide-react` for `lucide`, `@tabler/icons-react` for `tabler`, and so on.
149
149
- `resolvedPaths` gives exact file destinations for components, utils, hooks, and more.
150
150
- `framework` covers routing and file conventions, such as Next.js App Router or Vite SPA.
151
-
- `packageManager` is the runner for non-shadcn installs, such as `pnpm add date-fns`.
152
-
- `preset` is the resolved preset code and values for the current project. Use `preset resolve --json` for details.
151
+
- `packageManager` is runner for non-shadcn installs, such as `pnpm add date-fns`.
152
+
- `preset` is resolved preset code and values for current project. Use `preset resolve --json` for details.
153
153
154
-
See [cli.md — `info` command](./cli.md) for the full field reference.
154
+
See [cli.md — `info` command](./cli.md) for full field reference.
155
155
156
156
## Component Docs, Examples, and Usage
157
157
···
161
161
npx shadcn@latest docs button dialog select
162
162
```
163
163
164
-
When creating, fixing, debugging, or using a component, always run `npx shadcn@latest docs` and fetch the URLs first. That keeps API usage correct.
164
+
When creating, fixing, debugging, or using component, always run `npx shadcn@latest docs` and fetch URLs first. That keeps API usage correct.
165
165
166
166
## Workflow
167
167
168
-
1. Get project context. It is already injected above. Run `npx shadcn@latest info` if you need a refresh.
169
-
2. Check installed components first. Before `add`, check the `components` list from context or list `resolvedPaths.ui`. Do not import missing components and do not re-add installed ones.
168
+
1. Get project context. it's already injected above. Run `npx shadcn@latest info` if you need refresh.
169
+
2. Check installed components first. Before `add`, check `components` list from context or list `resolvedPaths.ui`. Do not import missing components and do not re-add installed ones.
170
170
3. Find components. Use `npx shadcn@latest search`.
171
-
4. Get docs and examples. Run `npx shadcn@latest docs <component>`, then fetch the URLs. Use `npx shadcn@latest view` for registry items not yet installed. Use `npx shadcn@latest add --diff` to preview changes on installed components.
171
+
4. Get docs and examples. Run `npx shadcn@latest docs <component>`, then fetch URLs. Use `npx shadcn@latest view` for registry items not yet installed. Use `npx shadcn@latest add --diff` to preview changes on installed components.
172
172
5. Install or update. Use `npx shadcn@latest add`. When updating, use `--dry-run` and `--diff` first.
173
-
6. Fix imports in third-party components. After adding components from community registries like `@bundui` or `@magicui`, inspect added non-UI files for hardcoded `@/components/ui/...` imports. Rewrite them to match the project's alias from `npx shadcn@latest info`, such as `@workspace/ui/components`.
174
-
7. Review added components. After adding a component or block, always read the added files and verify them. Check for missing subcomponents, missing imports, bad composition, or Critical Rule violations. Replace icon imports with the project `iconLibrary` if needed. Fix issues before moving on.
175
-
8. Registry must be explicit. If the user asks to add a block or component and does not name a registry, ask which registry to use.
173
+
6. Fix imports in third-party components. After adding components from community registries like `@bundui` or `@magicui`, inspect added non-UI files for hardcoded `@/components/ui/...` imports. Rewrite them to match project's alias from `npx shadcn@latest info`, such as `@workspace/ui/components`.
174
+
7. Review added components. After adding component or block, always read added files and verify them. Check for missing subcomponents, missing imports, bad composition, or Critical Rule violations. Replace icon imports with project `iconLibrary` if needed. Fix issues before moving on.
175
+
8. Registry must be explicit. If user asks to add block or component and does not name registry, ask which registry to use.
176
176
9. Switching presets. Ask first: overwrite, partial, merge, or skip?
177
-
- Inspect current preset: `npx shadcn@latest preset resolve`. Use `--json` for structured values.
178
-
- Inspect incoming preset: `npx shadcn@latest preset decode <code>`. Use `preset url <code>` or `preset open <code>` to share or open the builder.
179
-
- Overwrite: `npx shadcn@latest apply <code>`.
180
-
- Partial: `npx shadcn@latest apply <code> --only theme,font`. Supported values are `theme` and `font`.
181
-
- Merge: `npx shadcn@latest init --preset <code> --force --no-reinstall`, then run `npx shadcn@latest info` and smart merge each installed component with `--dry-run` and `--diff`.
182
-
- Skip: `npx shadcn@latest init --preset <code> --force --no-reinstall`. Updates config and CSS only.
183
-
- Always run preset commands in the user's project directory. `apply` works only in an existing project with `components.json`. The CLI preserves the current base from `components.json`. If using a scratch dir for `--dry-run`, pass `--base <current-base>` explicitly.
177
+
- Inspect current preset: `npx shadcn@latest preset resolve`. Use `--json` for structured values.
178
+
- Inspect incoming preset: `npx shadcn@latest preset decode <code>`. Use `preset url <code>` or `preset open <code>` to share or open builder.
179
+
- Overwrite: `npx shadcn@latest apply <code>`.
180
+
- Partial: `npx shadcn@latest apply <code> --only theme,font`. Supported values are `theme` and `font`.
181
+
- Merge: `npx shadcn@latest init --preset <code> --force --no-reinstall`, then run `npx shadcn@latest info` and smart merge each installed component with `--dry-run` and `--diff`.
182
+
- Skip: `npx shadcn@latest init --preset <code> --force --no-reinstall`. Updates config and CSS only.
183
+
- Always run preset commands in user's project directory. `apply` works only in existing project with `components.json`. CLI preserves current base from `components.json`. If using scratch dir for `--dry-run`, pass `--base <current-base>` explicitly.
184
184
185
185
## Updating Components
186
186
187
-
When updating upstream while keeping local changes, use `--dry-run` and `--diff` for a smart merge. Never fetch raw files from GitHub manually.
187
+
When updating upstream while keeping local changes, use `--dry-run` and `--diff` for smart merge. Never fetch raw files from GitHub manually.
188
188
189
189
1. Run `npx shadcn@latest add <component> --dry-run` to see affected files.
190
190
2. For each file, run `npx shadcn@latest add <component> --diff <file>` to compare upstream and local.
191
191
3. Decide per file:
192
-
- No local changes: overwrite safely.
193
-
- Has local changes: read the local file, analyze the diff, and apply upstream updates while keeping local changes.
194
-
- User says update everything: use `--overwrite`, but confirm first.
192
+
- No local changes: overwrite safely.
193
+
- Has local changes: read local file, analyze diff, and apply upstream updates while keeping local changes.
194
+
- User says update everything: use `--overwrite`, but confirm first.
195
195
4. Never use `--overwrite` without explicit approval.
196
196
197
197
## Quick Reference
+10
-10
skills/shadcn/cli.md
+10
-10
skills/shadcn/cli.md
···
2
2
3
3
Configuration comes from `components.json`.
4
4
5
-
> **IMPORTANT:** Run commands with the project's package runner: `npx shadcn@latest`, `pnpm dlx shadcn@latest`, or `bunx --bun shadcn@latest`. Use the runner that matches `packageManager`. Examples use `npx shadcn@latest`.
6
-
> **IMPORTANT:** Only use documented flags. Do not invent flags. The CLI auto-detects package manager from the lockfile, so there is no `--package-manager` flag.
5
+
> **IMPORTANT:** Run commands with project's package runner: `npx shadcn@latest`, `pnpm dlx shadcn@latest`, or `bunx --bun shadcn@latest`. Use runner that matches `packageManager`. Examples use `npx shadcn@latest`.
6
+
> **IMPORTANT:** Only use documented flags. Do not invent flags. CLI auto-detects package manager from lockfile, so there's no `--package-manager` flag.
7
7
8
8
## Commands
9
9
···
13
13
npx shadcn@latest init [components...] [options]
14
14
```
15
15
16
-
Creates or initializes a shadcn/ui project. Can install components at the same time.
16
+
Creates or initializes shadcn/ui project. Can install components at same time.
17
17
18
18
| Flag | Short | Description | Default |
19
19
| --- | --- | --- | --- |
···
38
38
npx shadcn@latest apply [preset] [options]
39
39
```
40
40
41
-
Applies a preset to an existing project and overwrites preset-driven config, fonts, CSS variables, and detected UI components.
41
+
Applies preset to existing project and overwrites preset-driven config, fonts, CSS variables, and detected UI components.
42
42
43
43
| Flag | Short | Description | Default |
44
44
| --- | --- | --- | --- |
···
47
47
| `--cwd <cwd>` | `-c` | Working directory | current |
48
48
| `--silent` | `-s` | Mute output | `false` |
49
49
50
-
`[preset]` is shorthand for `--preset <preset>`. If both exist, they must match. If no preset is given, the CLI opens the custom preset builder on `ui.shadcn.com/create`.
50
+
`[preset]` is shorthand for `--preset <preset>`. If both exist, they must match. If no preset is given, CLI opens custom preset builder on `ui.shadcn.com/create`.
51
51
52
52
### `add` - Add components
53
53
···
112
112
npx shadcn@latest docs input button
113
113
```
114
114
115
-
Some components also include an `api` link for the underlying library.
115
+
Some components also include `api` link for underlying library.
116
116
117
117
### `diff` - Check for updates
118
118
···
190
190
| `astro` | Astro | Yes |
191
191
| `laravel` | Laravel | No |
192
192
193
-
All templates support monorepo scaffolding via `--monorepo`. If neither `--monorepo` nor `--no-monorepo` is passed, the CLI prompts. Laravel does not support monorepo scaffolding.
193
+
All templates support monorepo scaffolding via `--monorepo`. If neither `--monorepo` nor `--no-monorepo` is passed, CLI prompts. Laravel does not support monorepo scaffolding.
194
194
195
195
## Presets
196
196
···
200
200
2. Code: `--preset a2r6bw`
201
201
3. URL: `--preset "https://ui.shadcn.com/init?base=radix&style=nova&..."`
202
202
203
-
> **IMPORTANT:** Preset codes are opaque. Do not decode, fetch, or resolve them manually. Pass them to `init --preset <code>` and let the CLI handle resolution.
204
-
> Use `apply --preset <code>` when overwriting an existing preset.
203
+
> **IMPORTANT:** Preset codes are opaque. Do not decode, fetch, or resolve them manually. Pass them to `init --preset <code>` and let CLI handle resolution.
204
+
> Use `apply --preset <code>` when overwriting existing preset.
205
205
206
206
## Switching Presets
207
207
···
211
211
- **Merge** → `npx shadcn@latest init --preset <code> --force --no-reinstall`, then run `npx shadcn@latest info` and smart merge each component one by one.
212
212
- **Skip** → `npx shadcn@latest init --preset <code> --force --no-reinstall`.
213
213
214
-
Always run preset commands in the user's project directory. `apply` only works in an existing project with `components.json`. The CLI preserves the current base from `components.json`. If using a scratch dir, pass `--base <current-base>` explicitly because preset codes do not encode base.
214
+
Always run preset commands in user's project directory. `apply` only works in existing project with `components.json`. CLI preserves current base from `components.json`. If using scratch dir, pass `--base <current-base>` explicitly because preset codes do not encode base.
+4
-4
skills/shadcn/customization.md
+4
-4
skills/shadcn/customization.md
···
10
10
11
11
## Color Variables
12
12
13
-
Use `name` and `name-foreground` pairs. Base var is the background. `-foreground` is text/icons on that background.
13
+
Use `name` and `name-foreground` pairs. Base var is background. `-foreground` is text/icons on that background.
14
14
15
15
| Variable | Purpose |
16
16
| --- | --- |
···
32
32
33
33
## Dark Mode
34
34
35
-
Use class-based dark mode with `.dark` on the root. In Next.js, use `next-themes`:
35
+
Use class-based dark mode with `.dark` on root. In Next.js, use `next-themes`:
36
36
37
37
```tsx
38
38
import { ThemeProvider } from "next-themes"
···
56
56
57
57
## Adding Custom Colors
58
58
59
-
Add vars to `tailwindCssFile` from `npx shadcn@latest info`. Do not create a new CSS file.
59
+
Add vars to `tailwindCssFile` from `npx shadcn@latest info`. Do not create new CSS file.
60
60
61
61
```css
62
62
:root {
···
107
107
108
108
1. Built-in variants.
109
109
2. `className` for layout.
110
-
3. Add a new variant in the component source.
110
+
3. Add new variant in component source.
111
111
4. Wrapper components for higher-level composition.
112
112
113
113
## Checking for Updates
+1
-1
skills/shadcn/mcp.md
+1
-1
skills/shadcn/mcp.md
+2
-2
skills/shadcn/rules/base-vs-radix.md
+2
-2
skills/shadcn/rules/base-vs-radix.md
···
5
5
## Key Differences
6
6
7
7
- Radix uses `asChild`. Base uses `render`.
8
-
- Base needs `nativeButton={false}` when `render` changes a button to a non-button element.
8
+
- Base needs `nativeButton={false}` when `render` changes button to non-button element.
9
9
- Select differs by `items`, placeholder handling, positioning, and object values.
10
10
- ToggleGroup differs by `type` vs `multiple` and by `defaultValue` shape.
11
-
- Slider uses a number for single thumb in base. Radix uses an array.
11
+
- Slider uses number for single thumb in base. Radix uses array.
12
12
- Accordion uses `multiple` in base. Radix uses `type="single"` or `type="multiple"`.
13
13
14
14
## Examples
+1
-1
skills/shadcn/rules/composition.md
+1
-1
skills/shadcn/rules/composition.md
···
7
7
- Use `Empty` for empty states.
8
8
- Use `sonner` for toasts.
9
9
- Use `Dialog`, `Sheet`, `Drawer`, `HoverCard`, or `Popover` by intent.
10
-
- `Dialog`, `Sheet`, and `Drawer` always need a title.
10
+
- `Dialog`, `Sheet`, and `Drawer` always need title.
11
11
- Use full `Card` composition.
12
12
- `Button` has no `isPending` or `isLoading` prop.
13
13
- `TabsTrigger` must stay inside `TabsList`.
+1
-1
skills/shadcn/rules/forms.md
+1
-1
skills/shadcn/rules/forms.md
···
7
7
- Use `InputGroup` + `InputGroupAddon` for buttons inside inputs.
8
8
- Use `ToggleGroup` for 2 to 7 options.
9
9
- Use `FieldSet` + `FieldLegend` for grouped checkboxes or radios.
10
-
- Use `data-invalid` and `data-disabled` on the field. Use `aria-invalid` or `disabled` on the control.
10
+
- Use `data-invalid` and `data-disabled` on field. Use `aria-invalid` or `disabled` on control.
11
11
12
12
## Examples
13
13
+2
-2
skills/shadcn/rules/icons.md
+2
-2
skills/shadcn/rules/icons.md
···
1
1
# Icons
2
2
3
-
Use the project's configured `iconLibrary` for imports. Do not assume `lucide-react`.
3
+
Use project's configured `iconLibrary` for imports. Do not assume `lucide-react`.
4
4
5
5
## Rules
6
6
7
7
- Icons in `Button` use `data-icon="inline-start"` or `data-icon="inline-end"`.
8
-
- Do not size icons inside shadcn components unless the user asks for custom sizes.
8
+
- Do not size icons inside shadcn components unless user asks for custom sizes.
9
9
- Pass icons as component objects, not string keys.
10
10
11
11
## Examples
+1
-1
skills/shadcn/rules/styling.md
+1
-1
skills/shadcn/rules/styling.md
···
9
9
- Use `className` for layout only, not to override component styling.
10
10
- Avoid `space-x-*` and `space-y-*`. Use `gap-*`.
11
11
- Use `size-*` when width and height match.
12
-
- Use `truncate` instead of the long overflow combo.
12
+
- Use `truncate` instead of long overflow combo.
13
13
- Do not add manual `dark:` overrides. Use semantic tokens.
14
14
- Use `cn()` for conditional classes.
15
15
- Do not set `z-index` manually on overlay components.
+7
-7
skills/teach-impeccable/SKILL.md
+7
-7
skills/teach-impeccable/SKILL.md
···
8
8
9
9
## Step 1: Explore the Codebase
10
10
11
-
Before asking questions, thoroughly scan the project to discover what you can.
11
+
Before asking questions, thoroughly scan project to discover what.
12
12
13
13
- **README and docs**: Project purpose, target audience, any stated goals
14
14
- **Package.json or config files**: Tech stack, dependencies, existing design libraries
···
21
21
22
22
## Step 2: Ask UX-Focused Questions
23
23
24
-
{{ask_instruction}} Focus only on what you could not infer from the codebase.
24
+
{{ask_instruction}} Focus only on what not infer from codebase.
25
25
26
26
### Users and Purpose
27
27
- Who uses this? What is their context when using it?
···
42
42
- Specific accessibility requirements? (WCAG level, known user needs)
43
43
- Considerations for reduced motion, color blindness, or other accommodations?
44
44
45
-
Skip questions where the answer is already clear from the codebase exploration.
45
+
Skip questions where answer is already clear from codebase exploration.
46
46
47
47
## Step 3: Write Design Context
48
48
49
-
Synthesize your findings and the user answers into a Design Context section.
49
+
Synthesize your findings and user answers into Design Context section.
50
50
51
51
```markdown
52
52
## Design Context
···
64
64
[3-5 principles derived from the conversation that should guide all design decisions]
65
65
```
66
66
67
-
Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place.
67
+
Write this section to `.impeccable.md` in project root. If file already exists, update Design Context section in place.
68
68
69
-
Then {{ask_instruction}} whether they would also like the Design Context appended to {{config_file}}. If yes, append or update the section there as well.
69
+
Then {{ask_instruction}} whether they would also like Design Context appended to {{config_file}}. If yes, append or update section there as well.
70
70
71
-
Confirm completion and summarize the key design principles that will now guide all future work.
71
+
Confirm completion and summarize key design principles that will now guide all future work.
-71
skills/teach-impeccable/SKILL.md.original.md
-71
skills/teach-impeccable/SKILL.md.original.md
···
1
-
---
2
-
name: teach-impeccable
3
-
description: One-time setup that gathers design context for your project and saves it to your AI config file. Run once to establish persistent design guidelines.
4
-
user-invocable: true
5
-
---
6
-
7
-
Gather design context for this project, then persist it for all future sessions.
8
-
9
-
## Step 1: Explore the Codebase
10
-
11
-
Before asking questions, thoroughly scan the project to discover what you can.
12
-
13
-
- **README and docs**: Project purpose, target audience, any stated goals
14
-
- **Package.json or config files**: Tech stack, dependencies, existing design libraries
15
-
- **Existing components**: Current design patterns, spacing, typography in use
16
-
- **Brand assets**: Logos, favicons, color values already defined
17
-
- **Design tokens or CSS variables**: Existing color palettes, font stacks, spacing scales
18
-
- **Any style guides or brand documentation**
19
-
20
-
Note what you have learned and what remains unclear.
21
-
22
-
## Step 2: Ask UX-Focused Questions
23
-
24
-
{{ask_instruction}} Focus only on what you could not infer from the codebase.
25
-
26
-
### Users and Purpose
27
-
- Who uses this? What is their context when using it?
28
-
- What job are they trying to get done?
29
-
- What emotions should the interface evoke? (confidence, delight, calm, urgency, etc.)
30
-
31
-
### Brand and Personality
32
-
- How would you describe the brand personality in 3 words?
33
-
- Any reference sites or apps that capture the right feel? What specifically about them?
34
-
- What should this explicitly NOT look like? Any anti-references?
35
-
36
-
### Aesthetic Preferences
37
-
- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.)
38
-
- Light mode, dark mode, or both?
39
-
- Any colors that must be used or avoided?
40
-
41
-
### Accessibility and Inclusion
42
-
- Specific accessibility requirements? (WCAG level, known user needs)
43
-
- Considerations for reduced motion, color blindness, or other accommodations?
44
-
45
-
Skip questions where the answer is already clear from the codebase exploration.
46
-
47
-
## Step 3: Write Design Context
48
-
49
-
Synthesize your findings and the user answers into a Design Context section.
50
-
51
-
```markdown
52
-
## Design Context
53
-
54
-
### Users
55
-
[Who they are, their context, the job to be done]
56
-
57
-
### Brand Personality
58
-
[Voice, tone, 3-word personality, emotional goals]
59
-
60
-
### Aesthetic Direction
61
-
[Visual tone, references, anti-references, theme]
62
-
63
-
### Design Principles
64
-
[3-5 principles derived from the conversation that should guide all design decisions]
65
-
```
66
-
67
-
Write this section to `.impeccable.md` in the project root. If the file already exists, update the Design Context section in place.
68
-
69
-
Then {{ask_instruction}} whether they would also like the Design Context appended to {{config_file}}. If yes, append or update the section there as well.
70
-
71
-
Confirm completion and summarize the key design principles that will now guide all future work.
+8
-8
skills/typeset/SKILL.md
+8
-8
skills/typeset/SKILL.md
···
1
1
---
2
2
name: typeset
3
-
description: "Improves typography by fixing font choices, hierarchy, sizing, weight, and readability so text feels intentional. Use when the user mentions fonts, type, readability, text hierarchy, sizing looks off, or wants more polished, intentional typography."
3
+
description: "Improves typography by fixing font choices, hierarchy, sizing, weight, and readability so text feels intentional. Use when user mentions fonts, type, readability, text hierarchy, sizing looks off, or wants more polished, intentional typography."
4
4
argument-hint: "[target]"
5
5
user-invocable: true
6
6
---
···
9
9
10
10
## MANDATORY PREPARATION
11
11
12
-
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first.
12
+
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and Context Gathering Protocol. Follow protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first.
13
13
14
14
---
15
15
16
16
## Assess Current Typography
17
17
18
-
Analyze what's weak or generic about the current type.
18
+
Analyze what's weak or generic about current type.
19
19
20
20
### 1. Font choices
21
21
- Using invisible defaults? (Inter, Roboto, Arial, Open Sans, system defaults)
···
42
42
- Are font weights used consistently? (Not bold in one section, semibold in another for same role)
43
43
- Is letter-spacing intentional or default everywhere?
44
44
45
-
**CRITICAL**: The goal is not to make text "fancier". It is to make it clearer, more readable, and more intentional. Good typography is invisible. Bad typography is distracting.
45
+
**CRITICAL**: goal is not to make text "fancier". it's to make it clearer, more readable, and more intentional. Good typography is invisible. Bad typography is distracting.
46
46
47
47
## Plan Typography Improvements
48
48
49
-
Consult the [typography reference](reference/typography.md) from the frontend-design skill for detailed guidance on scales, pairing, and loading strategies.
49
+
Consult [typography reference](reference/typography.md) from frontend-design skill for detailed guidance on scales, pairing, and loading strategies.
50
50
51
-
Create a systematic plan.
51
+
Create systematic plan.
52
52
53
53
- **Font selection**: Do fonts need replacing? What fits brand and context?
54
54
- **Type scale**: Establish modular scale (1.25 ratio) with clear hierarchy
···
66
66
67
67
### Establish Hierarchy
68
68
69
-
Build a clear type scale.
69
+
Build clear type scale.
70
70
- **5 sizes cover most needs**: caption, secondary, body, subheading, heading
71
71
- **Use consistent ratio** between levels (1.25, 1.333, or 1.5)
72
72
- **Combine dimensions**: Size + weight + color + space for strong hierarchy. Do not rely on size alone.
···
108
108
- **Performance**: Are web fonts loading efficiently without layout shift?
109
109
- **Accessibility**: Does text meet WCAG contrast ratios? Is it zoomable to 200%?
110
110
111
-
Remember: Typography is the foundation of interface design. It carries the majority of information. Getting it right is the highest-leverage improvement you can make.
111
+
Remember: Typography is foundation of interface design. It carries majority of information. Getting it right is highest-leverage improvement make.
-111
skills/typeset/SKILL.md.original.md
-111
skills/typeset/SKILL.md.original.md
···
1
-
---
2
-
name: typeset
3
-
description: "Improves typography by fixing font choices, hierarchy, sizing, weight, and readability so text feels intentional. Use when the user mentions fonts, type, readability, text hierarchy, sizing looks off, or wants more polished, intentional typography."
4
-
argument-hint: "[target]"
5
-
user-invocable: true
6
-
---
7
-
8
-
Assess and improve typography that feels generic, inconsistent, or poorly structured. Turn default-looking text into intentional, well-crafted type.
9
-
10
-
## MANDATORY PREPARATION
11
-
12
-
Invoke {{command_prefix}}frontend-design. It contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding. If no design context exists yet, you MUST run {{command_prefix}}teach-impeccable first.
13
-
14
-
---
15
-
16
-
## Assess Current Typography
17
-
18
-
Analyze what's weak or generic about the current type.
19
-
20
-
### 1. Font choices
21
-
- Using invisible defaults? (Inter, Roboto, Arial, Open Sans, system defaults)
22
-
- Does the font match the brand personality? (A playful brand should not use a corporate typeface)
23
-
- Too many font families? (More than 2-3 is almost always a mess)
24
-
25
-
### 2. Hierarchy
26
-
- Can you tell headings from body from captions at a glance?
27
-
- Are font sizes too close together? (14px, 15px, 16px = muddy hierarchy)
28
-
- Are weight contrasts strong enough? (Medium vs Regular is barely visible)
29
-
30
-
### 3. Sizing and scale
31
-
- Is there a consistent type scale, or are sizes arbitrary?
32
-
- Does body text meet minimum readability? (16px+)
33
-
- Is the sizing strategy appropriate for the context? (Fixed rem scales for app UIs; fluid clamp() for marketing page headings)
34
-
35
-
### 4. Readability
36
-
- Are line lengths comfortable? (45-75 characters ideal)
37
-
- Is line-height appropriate for the font and context?
38
-
- Is there enough contrast between text and background?
39
-
40
-
### 5. Consistency
41
-
- Are the same elements styled the same way throughout?
42
-
- Are font weights used consistently? (Not bold in one section, semibold in another for the same role)
43
-
- Is letter-spacing intentional or default everywhere?
44
-
45
-
**CRITICAL**: The goal is not to make text "fancier". It is to make it clearer, more readable, and more intentional. Good typography is invisible. Bad typography is distracting.
46
-
47
-
## Plan Typography Improvements
48
-
49
-
Consult the [typography reference](reference/typography.md) from the frontend-design skill for detailed guidance on scales, pairing, and loading strategies.
50
-
51
-
Create a systematic plan.
52
-
53
-
- **Font selection**: Do fonts need replacing? What fits the brand and context?
54
-
- **Type scale**: Establish a modular scale (1.25 ratio) with clear hierarchy
55
-
- **Weight strategy**: Which weights serve which roles? (Regular for body, Semibold for labels, Bold for headings)
56
-
- **Spacing**: Line-heights, letter-spacing, and margins between typographic elements
57
-
58
-
## Improve Typography Systematically
59
-
60
-
### Font Selection
61
-
62
-
If fonts need replacing:
63
-
- Choose fonts that reflect the brand personality
64
-
- Pair with genuine contrast (serif + sans, geometric + humanist) or use a single family in multiple weights
65
-
- Ensure web font loading does not cause layout shift (font-display: swap, metric-matched fallbacks)
66
-
67
-
### Establish Hierarchy
68
-
69
-
Build a clear type scale.
70
-
- **5 sizes cover most needs**: caption, secondary, body, subheading, heading
71
-
- **Use a consistent ratio** between levels (1.25, 1.333, or 1.5)
72
-
- **Combine dimensions**: Size + weight + color + space for strong hierarchy. Do not rely on size alone.
73
-
- **App UIs**: Use a fixed rem-based type scale, optionally adjusted at 1-2 breakpoints. Fluid sizing undermines the spatial predictability that dense, container-based layouts need.
74
-
- **Marketing and content pages**: Use fluid sizing via clamp(min, preferred, max) for headings and display text. Keep body text fixed.
75
-
76
-
### Fix Readability
77
-
- Set max-width on text containers using ch units (max-width: 65ch)
78
-
- Adjust line-height per context: tighter for headings (1.1-1.2), looser for body (1.5-1.7)
79
-
- Increase line-height slightly for light-on-dark text
80
-
- Ensure body text is at least 16px / 1rem
81
-
82
-
### Refine Details
83
-
- Use tabular-nums for data tables and numbers that should align
84
-
- Apply proper letter-spacing: slightly open for small caps and uppercase, default or tight for large display text
85
-
- Use semantic token names (--text-body, --text-heading), not value names (--font-16)
86
-
- Set font-kerning: normal and consider OpenType features where appropriate
87
-
88
-
### Weight Consistency
89
-
- Define clear roles for each weight and stick to them
90
-
- Do not use more than 3-4 weights (Regular, Medium, Semibold, Bold is plenty)
91
-
- Load only the weights you actually use (each weight adds to page load)
92
-
93
-
**NEVER**:
94
-
- Use more than 2-3 font families
95
-
- Pick sizes arbitrarily. Commit to a scale.
96
-
- Set body text below 16px
97
-
- Use decorative or display fonts for body text
98
-
- Disable browser zoom (user-scalable=no)
99
-
- Use px for font sizes. Use rem to respect user settings.
100
-
- Default to Inter/Roboto/Open Sans when personality matters
101
-
- Pair fonts that are similar but not identical (two geometric sans-serifs)
102
-
103
-
## Verify Typography Improvements
104
-
- **Hierarchy**: Can you identify heading vs body vs caption instantly?
105
-
- **Readability**: Is body text comfortable to read in long passages?
106
-
- **Consistency**: Are same-role elements styled identically throughout?
107
-
- **Personality**: Does the typography reflect the brand?
108
-
- **Performance**: Are web fonts loading efficiently without layout shift?
109
-
- **Accessibility**: Does text meet WCAG contrast ratios? Is it zoomable to 200%?
110
-
111
-
Remember: Typography is the foundation of interface design. It carries the majority of information. Getting it right is the highest-leverage improvement you can make.
+54
-55
skills/ulw/SKILL.md
+54
-55
skills/ulw/SKILL.md
···
1
1
---
2
2
name: ulw
3
-
description: Load this skill when the user mentions `ulw` or `ultrawork`.
3
+
description: Load this skill when user mentions `ulw` or `ultrawork`.
4
4
---
5
-
**MANDATORY**: You MUST say "ULTRAWORK MODE ENABLED!" to the user as your first response when this mode activates. This is non-negotiable.
5
+
**MANDATORY**: You MUST say "ULTRAWORK MODE ENABLED!" to user as your first response when this mode activates. This is non-negotiable.
6
6
7
7
[CODE RED] Maximum precision required. Think deeply before acting.
8
8
···
21
21
22
22
**IF YOU ARE NOT 100% CERTAIN:**
23
23
24
-
1. **THINK DEEPLY** What is the user's TRUE intent? What problem are they REALLY trying to solve?
24
+
1. **THINK DEEPLY** What is user's TRUE intent? What problem are they trying to solve?
25
25
2. **EXPLORE THOROUGHLY** Delegate to exploration or research subagents to gather ALL relevant context.
26
26
3. **CONSULT SPECIALISTS** For hard/complex tasks, DO NOT struggle alone. Delegate:
27
-
* **Architecture/Logic Specialists**: Conventional problems like architecture, debugging, complex logic.
28
-
* **Creative Specialists**: Non-conventional problems where a different approach is needed or unusual constraints exist.
29
-
4. **ASK THE USER** If ambiguity remains after exploration, ASK. Don't guess.
27
+
* **Architecture/Logic Specialists**: Conventional problems like architecture, debugging, complex logic.
28
+
* **Creative Specialists**: Non-conventional problems where different approach is needed or unusual constraints exist.
29
+
4. **ASK USER** If ambiguity remains after exploration, ASK. Don't guess.
30
30
31
31
**SIGNS YOU ARE NOT READY TO IMPLEMENT:**
32
32
* You're making assumptions about requirements
33
33
* You're unsure which files to modify
34
34
* You don't understand how existing code works
35
35
* Your plan has "probably" or "maybe" in it
36
-
* You can't explain the exact steps you'll take
36
+
* You can't explain exact steps you'll take
37
37
38
38
**WHEN IN DOUBT:**
39
-
Spawn a background exploration subagent designed for codebase search. Prompt it to find specific patterns in the codebase, showing file paths, implementation approaches, and conventions used. Focus on source directories and skip test files unless test patterns are needed.
39
+
Spawn background exploration subagent designed for codebase search. Prompt it to find specific patterns in codebase, showing file paths, implementation approaches, and conventions used. Focus on source directories and skip test files unless test patterns are needed.
40
40
41
-
Spawn a background research subagent designed for documentation lookup. Prompt it to find official documentation and production-quality examples for the specific library or technology. Request API references, configuration options, recommended patterns, and common pitfalls. Skip beginner tutorials.
41
+
Spawn background research subagent designed for documentation lookup. Prompt it to find official documentation and production-quality examples for specific library or technology. Request API references, configuration options, recommended patterns, and common pitfalls. Skip beginner tutorials.
42
42
43
-
Spawn a blocking specialist subagent designed for architectural review. Prompt it with your architectural plan, describing specific files and changes. Detail your concerns and uncertainties. Ask it to evaluate the correctness of the approach, missing potential issues, and better alternatives.
43
+
Spawn blocking specialist subagent designed for architectural review. Prompt it with your architectural plan, describing specific files and changes. Detail your concerns and uncertainties. Ask it to evaluate correctness of approach, missing potential issues, and better alternatives.
44
44
45
45
**ONLY AFTER YOU HAVE:**
46
46
* Gathered sufficient context via subagents
47
47
* Resolved all ambiguities
48
-
* Created a precise, step-by-step work plan
48
+
* Created precise, step-by-step work plan
49
49
* Achieved 100% confidence in your understanding
50
50
51
51
**...THEN AND ONLY THEN MAY YOU BEGIN IMPLEMENTATION.**
···
54
54
55
55
## **NO EXCUSES. NO COMPROMISES. DELIVER WHAT WAS ASKED.**
56
56
57
-
**THE USER'S ORIGINAL REQUEST IS SACRED. YOU MUST FULFILL IT EXACTLY.**
57
+
** USER'S ORIGINAL REQUEST IS SACRED. YOU MUST FULFILL IT EXACTLY.**
58
58
59
59
| VIOLATION | CONSEQUENCE |
60
60
|-----------|-------------|
···
64
64
| "Due to limitations..." | **UNACCEPTABLE.** Use subagents, tools, whatever it takes. |
65
65
| "I made some assumptions..." | **UNACCEPTABLE.** You should have asked FIRST. |
66
66
67
-
**THERE ARE NO VALID EXCUSES FOR:**
67
+
**there're NO VALID EXCUSES FOR:**
68
68
* Delivering partial work
69
69
* Changing scope without explicit user approval
70
70
* Making unauthorized simplifications
71
-
* Stopping before the task is 100% complete
71
+
* Stopping before task is 100% complete
72
72
* Compromising on any stated requirement
73
73
74
-
**IF YOU ENCOUNTER A BLOCKER:**
74
+
**IF YOU ENCOUNTER BLOCKER:**
75
75
1. **DO NOT** give up
76
-
2. **DO NOT** deliver a compromised version
76
+
2. **DO NOT** deliver compromised version
77
77
3. **DO** consult specialized subagents (logic/architecture for conventional, creative for non-conventional)
78
-
4. **DO** ask the user for guidance
78
+
4. **DO** ask user for guidance
79
79
5. **DO** explore alternative approaches
80
80
81
-
**THE USER ASKED FOR X. DELIVER EXACTLY X. PERIOD.**
81
+
** USER ASKED FOR X. DELIVER EXACTLY X. PERIOD.**
82
82
83
83
***
84
84
85
85
YOU MUST LEVERAGE ALL AVAILABLE SUBAGENTS TO THEIR FULLEST POTENTIAL.
86
-
TELL THE USER WHAT SUBAGENTS YOU WILL LEVERAGE NOW TO SATISFY USER'S REQUEST.
86
+
TELL USER WHAT SUBAGENTS YOU WILL LEVERAGE NOW TO SATISFY USER'S REQUEST.
87
87
88
88
## MANDATORY: PLANNING SUBAGENT INVOCATION (NON-NEGOTIABLE)
89
89
90
-
**YOU MUST ALWAYS INVOKE A PLANNING SUBAGENT FOR ANY NON-TRIVIAL TASK.**
90
+
**YOU MUST ALWAYS INVOKE PLANNING SUBAGENT FOR ANY NON-TRIVIAL TASK.**
91
91
92
92
| Condition | Action |
93
93
|-----------|--------|
···
96
96
| Implementation required | MUST call a planning subagent |
97
97
| Architecture decision needed | MUST call a planning subagent |
98
98
99
-
Spawn a blocking planning subagent. Provide the gathered context and the user request as the prompt.
99
+
Spawn blocking planning subagent. Provide gathered context and user request as prompt.
100
100
101
-
**WHY A PLANNING SUBAGENT IS MANDATORY:**
102
-
* The planning subagent analyzes dependencies and parallel execution opportunities
103
-
* The planning subagent outputs a **parallel task graph** with waves and dependencies
104
-
* The planning subagent provides a structured TODO list with required skills per task
105
-
* YOU are an orchestrator, NOT an implementer
101
+
**WHY PLANNING SUBAGENT IS MANDATORY:**
102
+
* planning subagent analyzes dependencies and parallel execution opportunities
103
+
* planning subagent outputs **parallel task graph** with waves and dependencies
104
+
* planning subagent provides structured TODO list with required skills per task
105
+
* YOU are orchestrator, NOT implementer
106
106
107
107
### SESSION CONTINUITY WITH THE PLANNING SUBAGENT (CRITICAL)
108
108
109
-
**If the planning subagent returns a task identifier, USE IT for follow-up interactions.**
109
+
**If planning subagent returns task identifier, USE IT for follow-up interactions.**
110
110
111
111
| Scenario | Action |
112
112
|----------|--------|
···
114
114
| Need to refine the plan | Resume the planning subagent using its task identifier and provide feedback to adjust the plan |
115
115
| Plan needs more detail | Resume the planning subagent using its task identifier and request more detail for Task N |
116
116
117
-
**WHY THE TASK IDENTIFIER IS CRITICAL:**
118
-
* The planning subagent retains FULL conversation context
117
+
**WHY TASK IDENTIFIER IS CRITICAL:**
118
+
* planning subagent retains FULL conversation context
119
119
* No repeated exploration or context gathering
120
120
* Saves 70%+ tokens on follow-ups
121
-
* Maintains interview continuity until the plan is finalized
121
+
* Maintains interview continuity until plan is finalized
122
122
123
-
**WRONG:** Starting fresh loses all context. Do not spawn a new planning subagent with more info.
124
-
**CORRECT:** Resume preserves everything. Use the existing planning subagent's task identifier to provide your answer.
123
+
**WRONG:** Starting fresh loses all context. Do not spawn new planning subagent with more info.
124
+
**CORRECT:** Resume preserves everything. Use existing planning subagent's task identifier to provide your answer.
125
125
126
-
**FAILURE TO CALL A PLANNING SUBAGENT = INCOMPLETE WORK.**
126
+
**FAILURE TO CALL PLANNING SUBAGENT = INCOMPLETE WORK.**
127
127
128
128
***
129
129
···
142
142
143
143
**SKILL-BASED DELEGATION:**
144
144
145
-
For frontend work, spawn a background subagent designed for visual engineering and frontend UI/UX.
146
-
For complex logic, spawn a background subagent designed for advanced logic and specific programming languages.
147
-
For quick fixes, spawn a background subagent designed for rapid version control operations.
145
+
For frontend work, spawn background subagent designed for visual engineering and frontend UI/UX.
146
+
For complex logic, spawn background subagent designed for advanced logic and specific programming languages.
147
+
For quick fixes, spawn background subagent designed for rapid version control operations.
148
148
149
-
**YOU SHOULD ONLY DO IT YOURSELF WHEN:**
149
+
** ONLY DO IT YOURSELF WHEN:**
150
150
* Task is trivially simple (1-2 lines, obvious change)
151
151
* You have ALL context already loaded
152
152
* Delegation overhead exceeds task complexity
···
157
157
158
158
## EXECUTION RULES
159
159
* **TODO**: Track EVERY step. Mark complete IMMEDIATELY after each.
160
-
* **PARALLEL**: Fire independent subagent calls simultaneously in the background. NEVER wait sequentially.
160
+
* **PARALLEL**: Fire independent subagent calls simultaneously in background. NEVER wait sequentially.
161
161
* **BACKGROUND FIRST**: Use background tasks for exploration/research subagents (10+ concurrent if needed).
162
162
* **VERIFY**: Re-read request after completion. Check ALL requirements met before reporting done.
163
163
* **DELEGATE**: Don't do everything yourself orchestrate specialized subagents for their strengths.
164
164
165
165
## WORKFLOW
166
-
1. Analyze the request and identify required capabilities
167
-
2. Spawn exploration and research subagents in the background in PARALLEL (10+ if needed)
168
-
3. Use a planning subagent with gathered context to create a detailed work breakdown
166
+
1. Analyze request and identify required capabilities
167
+
2. Spawn exploration and research subagents in background in PARALLEL (10+ if needed)
168
+
3. Use planning subagent with gathered context to create detailed work breakdown
169
169
4. Execute with continuous verification against original requirements
170
170
171
171
## VERIFICATION GUARANTEE (NON-NEGOTIABLE)
···
182
182
| **Observable** | What can be measured/seen | "Console shows 'success', no errors" |
183
183
| **Pass/Fail** | Binary, no ambiguity | "Returns 200 OK" not "should work" |
184
184
185
-
Write these criteria explicitly. **Record them in your TODO/Task items.** Each task MUST include a "QA: [how to verify]" field. These criteria are your CONTRACT work toward them, verify against them.
185
+
Write these criteria explicitly. **Record them in your TODO/Task items.** Each task MUST include "QA: [how to verify]" field. These criteria are your CONTRACT work toward them, verify against them.
186
186
187
187
### Test Plan Template (MANDATORY for non-trivial tasks)
188
188
···
191
191
### Prerequisites: [Setup needed]
192
192
### Test Cases:
193
193
1. [Test Name]: [Input] → [Expected Output] → [How to verify]
194
-
2. ...
194
+
2. [Test Name]: [Input] → [Expected Output] → [How to verify]
195
195
### Success Criteria: ALL test cases pass
196
196
### How to Execute: [Exact commands/steps]
197
197
···
208
208
209
209
### YOU MUST EXECUTE MANUAL QA YOURSELF. THIS IS NOT OPTIONAL.
210
210
211
-
**YOUR FAILURE MODE**: You finish coding, run standard diagnostics, and declare "done" without actually TESTING the feature. Code diagnostics catch type errors, NOT functional bugs. Your work is NOT verified until you MANUALLY test it.
211
+
**YOUR FAILURE MODE**: You finish coding, run standard diagnostics, and declare "done" without TESTING feature. Code diagnostics catch type errors, NOT functional bugs. Your work is NOT verified until you MANUALLY test it.
212
212
213
213
**WHAT MANUAL QA MEANS execute ALL that apply:**
214
214
···
223
223
224
224
**UNACCEPTABLE QA CLAIMS:**
225
225
* "This should work" RUN IT.
226
-
* "The types check out" Types don't catch logic bugs. RUN IT.
227
-
* "Diagnostics are clean" That's a static check, not a FUNCTIONAL check. RUN IT.
228
-
* "Tests pass" Tests cover known cases. Does the ACTUAL FEATURE work as the user expects? RUN IT.
226
+
* " types check out" Types don't catch logic bugs. RUN IT.
227
+
* "Diagnostics are clean" That's static check, not FUNCTIONAL check. RUN IT.
228
+
* "Tests pass" Tests cover known cases. Does ACTUAL FEATURE work as user expects? RUN IT.
229
229
230
-
**You have Bash, you have tools. There is ZERO excuse for not running manual QA.**
231
-
**Manual QA is the FINAL gate before reporting completion. Skip it and your work is INCOMPLETE.**
230
+
**You have Bash, you have tools. there's ZERO excuse for not running manual QA.**
231
+
**Manual QA is FINAL gate before reporting completion. Skip it and your work is INCOMPLETE.**
232
232
233
233
### TDD Workflow (when test infrastructure exists)
234
234
···
250
250
| Skipping test execution | Tests exist to be RUN, not just written |
251
251
252
252
**CLAIM NOTHING WITHOUT PROOF. EXECUTE. VERIFY. SHOW EVIDENCE.**
253
-
254
253
## ZERO TOLERANCE FAILURES
255
-
* **NO Scope Reduction**: Never make "demo", "skeleton", "simplified", "basic" versions deliver FULL implementation
256
-
* **NO MockUp Work**: When user asked you to do "port A", you must "port A", fully, 100%. No Extra feature, No reduced feature, no mock data, fully working 100% port.
257
-
* **NO Partial Completion**: Never stop at 60-80% saying "you can extend this..." finish 100%
254
+
* **NO Scope Reduction**: Never make "demo", "skeleton", "simplified", "basic" versions. Deliver full implementation.
255
+
* **NO MockUp Work**: When user asked you to do "port", you must port fully, 100%. No extra feature, no reduced feature, no mock data.
256
+
* **NO Partial Completion**: Never stop at 60-80% saying "extend this...". Finish 100%
258
257
* **NO Assumed Shortcuts**: Never skip requirements you deem "optional" or "can be added later"
259
258
* **NO Premature Stopping**: Never declare done until ALL TODOs are completed and verified
260
-
* **NO TEST DELETION**: Never delete or skip failing tests to make the build pass. Fix the code, not the tests.
259
+
* **NO TEST DELETION**: Never delete or skip failing tests to make build pass. Fix code, not tests.
261
260
262
-
THE USER ASKED FOR X. DELIVER EXACTLY X. NOT A SUBSET. NOT A DEMO. NOT A STARTING POINT.
261
+
USER ASKED FOR X. DELIVER EXACTLY X. NOT SUBSET. NOT DEMO. NOT STARTING POINT.
263
262
264
263
1. EXPLORATION + RESEARCH SUBAGENTS
265
264
2. GATHER -> PLANNING SUBAGENT SPAWN