polish-skill
Skill1 starsChanged 11 days agoMITView on GitHub
Fix design detail issues: spacing, alignment, consistency, token compliance. Use after audit or when visual inconsistencies are spotted. Do NOT use for structural redesign.
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 23
After audit finds P1-P2 theming/consistency issues
- Distinctive: line 24
When components look "off" but structurally work
- Distinctive: line 27
When design tokens exist but aren't applied consistently
≈ “Common” is an estimate: at least 1 in 5 of the 308,232 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Polish Skill
Fix design detail issues — spacing, alignment, consistency, token drift.
Where harden fixes technical issues, polish fixes visual ones. Works within the existing design system; does not redesign.
When to Use
- After
auditfinds P1-P2 theming/consistency issues - When components look "off" but structurally work
- User says "make this look more polished"
- During design QA before shipping
- When design tokens exist but aren't applied consistently
When NOT to Use
- Technical issues (use
harden) - UX flow issues (use
redesign,distill) - Structural redesign (use
redesign) - Copy rewriting (use
clarify)
Output Contract
| Artifact | Format | Location | Quality Criteria |
| Visual consistency fixes | CSS/token values | Source files | Token-compliant spacing, radius, shadows; no hardcoded values |
Process
1. Scan for Drift
Compare components against the design system tokens:
| What | Check |
| Spacing | Indents match the scale (4, 8, 12, 16, 24, 32, 48, 64) |
| Border radius | Consistent per component type (button: x, card: y) |
| Shadows | Elevation layers match token values |
| Colors | No hardcoded hexes outside token system |
| Type scale | Headings/body sizes match the type ramp |
| Alignment | Text, icons, and containers share baselines |
| Density | Padding/margin is consistent across similar components |
| Focus states | All interactive elements have the same focus style |
2. Fix by Category
Spacing
| Issue | Fix |
| Inconsistent padding between cards | Normalize to token spacing scale |
| Orphaned margins | Remove half-spacing gaps (use token multiples only) |
| Missing breathing room | Add gap between grouped elements |
| Crowded icons | Add horizontal gap between icon + text |
Alignment
| Issue | Fix |
| Misaligned form labels | Set consistent label width or grid |
| Icon-text baseline drift | Vertically align icon with text center |
| Button text not centered | Check flexbox / text-align on button |
| Input text padding | Normalize input left padding across form |
Consistency
| Issue | Fix |
| Mixed radius on same element type | Unify per component type |
| Mixed shadow depths | One elevation per layer (card, modal, toast) |
| Different hover effects | Same effect pattern across similar components |
| Mixed border weights | Normalize to token weights (0, 1, 2) |
Token Compliance
| Issue | Fix |
| Hardcoded value | Replace with design token |
| Wrong token usage | Replace with correct semantic token |
| Missing dark mode token | Add dark: variant |
3. Output Format
/polish the profile card
Fix 1: Spacing
- Before: padding 15px (not on scale)
- After: padding 16px (token --spacing-4)
Fix 2: Border radius
- Before: 12px
- After: 8px (token --radius-card)
Fix 3: Shadow
- Before: 0 4px 6px (custom)
- After: token --shadow-card (0 2px 8px)
Fix 4: Alignment
- Before: icon 2px above text baseline
- After: flex align-items: center4. Escalation Rules
| Finding | Escalate to |
| Wrong typeface, weight, or size | typeset |
| Missing tokens (need new ones) | Design system review |
| Layout breaks at breakpoint | adapt |
| Performance issue in animation | optimize |
| Confusing visual hierarchy | redesign, distill |
Pitfalls
- Over-polishing — Not every component needs to be perfect. Polish the ones users see.
- Changing design decisions — If the design intent is unclear, ask. Don't guess the designer's intent.
- Token zealotry — A one-off custom value with a clear reason is fine. Systematic drift is not.
QA Gates
- All spacing values on the token scale
- Consistent border radius per component type
- Shadow depth is consistent per elevation layer
- No hardcoded colors (confirmed token-only)
- Icons aligned with text baselines
- Hover/focus states consistent across similar components
- Dark mode tokens applied where missing
- No design decisions silently overridden
In this repository59 other files it gives its agents.
- AGENTS.mdAGENTS.md
- templates/CLAUDE.mdCLAUDE.md
- adapt-skillSkill
- api-and-interface-designSkill
- architecture-analysisSkill
- audit-skillSkill
- backend-api-masterySkill
- browser-testing-with-devtoolsSkill
- ci-cd-and-automationSkill
- clarify-skillSkill
- cli-toolsSkill
- code-review-and-qualitySkill
- code-simplificationSkill
- context-engineeringSkill
- critique-skillSkill
- customize-opencodeSkill
- debugging-and-error-recoverySkill
- debugging-three-strikesSkill
- delight-skillSkill
- deprecation-and-migrationSkill
- dev-environment-auditSkill
- documentation-and-adrsSkill
- doubt-driven-developmentSkill
- engineering-fundamentalsSkill
- frontend-desktopSkill
- frontend-mobileSkill
- frontend-pwaSkill
- frontend-ui-engineeringSkill
- frontend-webSkill
- fullstack-shippingSkill
- gateSkill
- git-init-and-versioningSkill
- git-workflow-and-versioningSkill
- hard-skillSkill
- idea-refineSkill
- incremental-implementationSkill
- industrial-brutalist-uiSkill
- interview-meSkill
- minimalist-uiSkill
- multi-agent-orchestrationSkill
- observability-and-instrumentationSkill
- optimize-skillSkill
- output-skillSkill
- performance-optimizationSkill
- planning-and-task-breakdownSkill
- project-health-checkSkill
- project-metricsSkill
- redesign-skillSkill
- security-and-hardeningSkill
- self-improvementSkill
- shipping-and-launchSkill
- skill-creatorSkill
- skill-improverSkill
- soft-premium-uiSkill
- source-driven-developmentSkill
- spec-driven-developmentSkill
- test-driven-developmentSkill
- typeset-skillSkill
- user-onboardingSkill
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
Reviews can't be read right now.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.